[texworks] Help files for Scripting
st.loeffler at gmail.com
Fri Jun 11 18:09:32 CEST 2021
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
> 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
>> -) 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
Automatic build of %H
>> -) 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.
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
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
> 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.
More information about the texworks