[texworks] Help files for Scripting

[Henrik Skov Midtiby]

Dear Stefan,

Thanks for the comments, I will comment on them one at a time.

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.

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].

> -) 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.

> -) 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

> -) 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.

> These are solely meant as suggestions for further improving the
> infrastructure, I fully realize that this is a first "proof-of-concept"
> right now.
Thanks for the inputs.

> ... (whether with R or pandoc or any other tool; producing a website, a pdf,
> an e-book, or whatever).
Right now I have an issue with building the pdf from the book as the
latex installation fails on travis.

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.
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.

Best regards,
Henrik

On Thu, 10 Jun 2021 at 06:39, Stefan Löffler <st.loeffler at gmail.com> wrote:
>
> Hi Henrik,
>
> On 08.06.21 14:22, Henrik Skov Midtiby wrote:
> > The system is now working ;-)
>
> That's awesome news! It looks very good. I had thought about roughly the
> same idea, but you were much faster in implementing it :).
>
> A few comments/questions/musings/suggestions:
>
> *) My main concern with this method was that every commit is essentially
> "doubled", i.e. for every commit to the master branch there will be a
> corresponding commit to the gh-pages branch. This seems kind of wasteful
> and blowing up the git history. But I haven't found any good way around
> it, unless we find a system other than bookdown that is supported
> natively by GitHub Pages/Jekyll (which is ruby-based, I think). One
> "alternative" would be to create two separate repositories (one for the
> sources, and one for the output) rather than a single repository with
> two branches. The benefit would be that (naive) cloning of the sources
> would not download all versions of the html output, but at the (IMO
> high) cost of having two completely detached repositories.
>
> *) Personally, I have come to preferring GitHub Actions over TravisCI.
> Functionally, they are pretty similar. I used to use travis for building
> TeXworks, until they abruptly introduced some quotas/usage limits a
> while back (plus their Windows version never worked for me, but that's
> irrelevant for the manuals). IMO, Github Actions also has the advantage
> of being hosted directly on Github, which might make some things
> (slightly) faster. There's also the possibility (with some trickery) to
> make "artifacts" available (such as, here, the latest pdf version of the
> manual)
>
> *) The deploy script could potentially benefit from:
> -) Commiting from the CI should ideally happen on behalf of the original
> commit's author
> -) 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?
> -) 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
>
> These are solely meant as suggestions for further improving the
> infrastructure, I fully realize that this is a first "proof-of-concept"
> right now.
>
> On 08.06.21 16:45, Paul A Norman wrote:
> > Would that be able potentially in the future to be set up under the
> > area that Stefan is looking at as suggested in his earlier postings –
> > do you think?
>
> Yes, absolutely. We'd just have to migrate the repository - piece of
> cake (hopefully ;)).
>
> > Downloading and producing locally and reposting resultant document(s),
> > seems a fair way to go.
> >
> > Would we use RStudio for production locally, or could we jump directly
> > to pandoc?
>
> Building it locally would only be required for testing purposes. To way
> Henrik set it up, you'd ultimately only have to push (publish) the
> changed source files and all the output would be built automatically
> (whether with R or pandoc or any other tool; producing a website, a pdf,
> an e-book, or whatever).
>
> > And I assume that a seperate project could conceivably handle the main
> > TeXworks manual?
> >
> > Or is there a case here, for just making the scripting API TwScript a
> > section of that TeXworks manual, or is it better to keep them both
> > separate from each other?
>
> Personally, I would prefer to keep them separate/independent. The reason
> being that the target audience is probably very different: on the one
> hand a user trying to learn how to use TeXworks, who probably doesn't
> want to see pages upon pages of "technical documentation"; on the other
> hand a script programmer how doesn't want to have to skip pages upon
> pages about downloading, installing, and using TeXworks for the first time.
>
> All the best,
> Stefan