[texworks] Help files for Scripting

Paul A Norman paul.a.norman at gmail.com
Tue Aug 10 09:02:34 CEST 2021


Hi,

Well it seemed helpful to prepare MD files for seeding the documentation
project here? :-)

So I've exported what seems to be a worthwhile selection of the current
project to MD from HelpNDoc Version: 7.5.0.435, apparently this will
meanwhile include a small banner as this is a free version of HelpNDoc. I
dont think that this must be retained as we go forward as we will be
substantially altering and updating the base MD anyway?

***
_Created with the Personal Edition of HelpNDoc: [Free Kindle producer](<
https://www.helpndoc.com/feature-tour/create-ebooks-for-amazon-kindle>)_

Looking at the directory of MD produced, I am not sure which might be the
entry document,any one more familiar with MD would have a better idea.
(There may have been a setting I missed in the export process -- but I
can't see one.)

I have culled the pages back in the original .hnd project first,
considerably, to try and get rid of what was obviously dead weight now, but
I can see that there is more that could yet go.

I've included this reduced Export helpndoc to MD 2021 08 10.hnd this is now
based on, and the original full file is still on TwScript.PaulANorman.info
for now as well.

HelpNDoc is available from—

https://www.helpndoc.com/download/

It is free for personal use and we had a clearance for TeXworks as an
OpenSource project as well.

Anyway, there may be another path, like having HelpNDoc export to html,
doc, or chm etc first then converting by other means to MD(?), hopefully
though this first step will help us going forward.

I would recommend using the enclosed .hnd with HelpnDoc to explore the
whole thing more thoroughly if trying to set the MD in any particular way
during the transition.
I have little experience with this -- but MD export templates can be
adjusted apparently, HelpNDoc itself is scriptable to some degree as well.

(I also see that HelpNDoc can produce/export a Qt formatted base help file
if that ever becomes relevant?)

Anyway let's see where we go from here...

Kindest Regards,
Paul

On Sat, 12 Jun 2021 at 04:09, Stefan Löffler <st.loeffler at gmail.com> wrote:

> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://tug.org/pipermail/texworks/attachments/20210810/08b41dcf/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Export TwScript helpndoc to MD.7z
Type: application/octet-stream
Size: 2046391 bytes
Desc: not available
URL: <https://tug.org/pipermail/texworks/attachments/20210810/08b41dcf/attachment-0001.obj>


More information about the texworks mailing list.