[texworks] Help files for Scripting

[Stefan Löffler]

Dear Henrik,

On 10.06.21 08:41, Henrik Skov Midtiby wrote:
> Regarding blowing up the size of the repository, it is also an issue
> that annoys me. I think it is possible for travis to overwrite the
> gh-pages banch in git, so the repository effectively only contains the
> last commit. Whether this will cause some issues when others start
> cloning the repository I cannot assess.

For the moment, I'm pretty firmly against (routinely) rewriting git 
histories. As you mention, this can cause problems with clones/updates. 
People wanting to contribute to the manual and not necessarily 
git-experts, so I would prefer not to force them to learn complex 
merging strategies, hard resets, or whatever may be necessary.

Actually, I don't even think the problem is particularly huge. Git only 
stores changes, and all these files are text files, which should 
compress well. So we're not talking GBs here.

There are some possibilities to alleviate this problem to a degree. E.g. 
instructing people to use `git clone --single-branch` for cloning (As 
the man page says, this clones "only the history leading to the tip of a 
single branch", i.e. the main branch, but not the gh-pages branch (or 
any other branches, for that matter)); or to use `git clone --depth 1` 
(which implies `--single-branch`, according to the man page) if no 
history is needed at all.

Another possibility would still be to have a separate repo "just for 
web-hosting" purposes. This would potentially allow to keep different 
parts (e.g., the user manual, the scripting documentation, and future 
GitHub hosted website - e.g. a page with links to scripts)) in separate 
repos. However, this would probably sort of work anyway, as separate 
repos could be mapped to similar urls such as texworks.github.io/manual, 
texworks.github.io/scripting-doc, etc.) The main questions of linking 
between them (consistently across output formats) remains, though (see 
also below).

> The choice of travis vs. github actions is completely open. I only
> choose travis as it was used as an example in the bookdown
> documentation. [https://bookdown.org/yihui/bookdown/github.html].

I see. I will look into how easily this could be ported to GitHub 
Actions at some point, but I think it should be straight-forward. One 
benefit would be that I think actions have write access to the repo they 
are run on, so comitting (to the gh-pages branch of the same repo) would 
work without tokens, authentication and all that stuff, quasi "out of 
the box".

>> -) Commiting from the CI should ideally happen on behalf of the
>> original commit's author
> That makes sense, however I have no idea of how to achieve this.

`git show -s --format="%aN <%aE>"` (in the source directory) should give 
the author information required, and `git commit --author="..."` can be 
used to set it during committing.
Additionally, a format string of %B can be used to get the full commit 
message (to potentially automatically include in the new commit), %H 
gives the full commit hash, %h the abbreviated commit hash.
So I'm thinking of a commit message along the lines

---------------8<----------------------
Automatic build of %H

%B
---------------8<----------------------


>> -) The case where files are deleted should be handled (probably
>> something along the lines of `rm *` before copying over the book) - or
>> is this handled and I missed it?
> Good catch. I missed the line "git rm -rf *" in the _deploy.sh script.
> It has now been fixed.
> https://github.com/henrikmidtiby/bookdown-testing/commit/7ff462cbbd6148855f0ca2c8b2ad4529a0bcb32c

Great.
Good thing this does not seem to remove dot-files like .nojekyll :).
We may want to "whitelist" some files in the future - such as a 
README.md to display on GitHub. But if that becomes relevant, it can 
simply be achieved by moving the file(s) in question out of the repo 
before removing everything and moving them back in the end.

>> -) We should check if this gracefully handles all cases (e.g., does the
>> commit fail if none of the output files have changed?) unless you have
>> done so already
> I haven't checked this yet.

It would seem that `git commit` returns an error (code 1) when there are 
no files to commit. Of course, errors could also mean something else, 
though, so they shouldn't all be quietly ignored.
However, `git diff --quiet HEAD` (which imples `--exit-code`) gives exit 
code 0 (no error) when there are no changes and exit code 1 when there 
are changes. (NB: the HEAD is required to detect both staged and 
unstaged changes; probably not super-important for us, but who knows)

> The benefit of having one joint manual with both an introduction to
> texworks and the scripting is that there is only one location to
> search for information and one repository to maintain.

One location to maintain can be advantageous, of course. However, it 
also means that everyone wanting to work on the user manual also has to 
download/clone all of the scripting docs, plus whatever may be added in 
the future.
FWIW, the manual will likely require some additional/specialized 
processing (it includes some fancy styling of key presses, OS-specific 
boxes, an index, etc.).

Re. "one location": they would be in "similar" locations (see above) in 
any case.

> The benefit of splitting the manuals is that they target different
> audiences and thus can address the audiences more directly. The issue
> of splitting information across several locations can be handled by
> suitable linking between the manuals.

Suitable linking may be slightly problematic (although this is 
independent of the number of repos). Unless everything is one gigantic 
monolithic document, I don't see an easy way to have proper links 
between documents (I might see a complicated one, though ;)). Linking 
from one website to another is no problem, of course, but when compiled 
to a PDF (E-book, or whatever), that link does not necessarily make any 
sense anymore. In addition, it would hard-code the URL of the github 
page, i.e. it would prevent people from mirroring the manual on their 
own network (say, a university/company network). One way around this 
might be to define "custom links" (á la "[section 1](api-docs:sect1)") 
which would have to be replaced in the pandoc stage (which supports such 
filters, AFAIK) and could be customized by each user compiling the 
documentation (and possibly also by output format). FWIW, I have to 
teach me how to write such replacement filters at some point anyway for 
the specialized processing of the user manual mentioned above.

Best regards,
Stefan