HTML Manual

[jkotlinski]

Hi all, I am consider to rewriting the manual in AsciiDoc format. Possibly to publish it in HTML only.

WHY:

• I imagine HTML is the most popular way to consume technical documentation. At least, that is true for me personally.
• Compared to LaTeX, AsciiDoc is a very simple language. Maybe switching to it would make it easier for others to contribute to documentation.

What do you think?

[jkotlinski]

A quick example how it could look: https://jkotlinski.github.io/durexforth/

[jkotlinski]

@lonetech Just a heads-up. I'm about to undo the work on adding word index to the manual.

Or, I guess there would still be a word index, but not as pretty...

[lonetech]

At this point, I think AsciiDoc (rendered via DocBook) may be the best option out there. We can fix the annoying commas using the index.term.separator attribute. By the way, the sample has \= instead of =.

%.xml: %.adoc
    asciidoctor -b docbook $<
%.html: %.xml
    xmlto --stringparam index.term.separator='" "' --skip-validation html-nochunks $<

For PDF output, this worked using fop but not dblatex.

[jkotlinski]

Yes, asciidoctor-fopub output is actually decent. Nice find!

I will just merge what is there now as a starting point. "make docs" does HTML only.

[jkotlinski]

One thing that annoys me greatly now is that I cannot add a preamble with a2x.

[lonetech]

AFAICT, the python asciidoc toolchain which contains a2x has confusingly been replaced with the ruby asciidoctor. May or may not matter.

What did you want to put in a preamble? Would command line attributes (-a for both asciidoctor and a2x) do? This seems a good mechanism for the revision info.

[jkotlinski]

The a2x ”revision history” is weird. I would like to replace with a simple text that says, ”this manual is for durexForth vx.x” or something like that. A problem with asciidoctor is that it does not support Index for HTML output. Maybe there is some way to solve that.

…

On Sun, 21 Aug 2022 at 16:16, Yann Vernier ***@***.***> wrote: AFAICT, the python asciidoc toolchain which contains a2x has confusingly been replaced with the ruby asciidoctor. May or may not matter. What did you want to put in a preamble? Would command line attributes <https://docs.asciidoctor.org/asciidoc/latest/attributes/reference-attributes/> (-a for both asciidoctor and a2x) do? This seems a good mechanism for the revision info. — Reply to this email directly, view it on GitHub <#468 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAY34O6XVJJU67TKPWE4YC3V2I24XANCNFSM56XKU4AA> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[lonetech]

Turns out, the lack of index in html is only using the direct html backend. The index is generated when using docbook-xsl, which is exactly what a2x does. The asciidoctor+xmlto combo I referred to earlier does produce html with index. So asciidoctor doesn't really lose index support, it adds a draft style html option which doesn't use docbook. Similarly asciidoctor-pdf can generate pdfs directly, but loses footnote support (they turn into end of chapter notes).

I wasn't aware of the revision history feature, and the first thing I found looking it up was an option to turn it off.

[jkotlinski]

I made a new setup in the Makefile, where "make docs" produces HTML output using asciidoctor-multipage. https://jkotlinski.github.io/durexforth/index.html
I think it looks mostly fine, there is some weirdness with the TOC being printed twice. Sadly it does not produce a word index.
Maybe asciidoctor-multipage is not a great option, but it is the best I found so far.

"make deploy" produces a PDF using asciidoctor-pdf . This part seems to work without a problem.

[jkotlinski]

Actually, asciidoctor-multipage seems fairly buggy. I switched back to plain asciidoctor and single-file HTML... I think it is ok option for now.

[jkotlinski]

The asciidoctor issue for supporting HTML indices is here : asciidoctor/asciidoctor#450

[lonetech]

Can't we simply use the docbook backend because it still supports index generation?

[jkotlinski]

All the toolings I tried had their own problems and bugs. Do you have some particular setup in mind?

…

On Wed, 24 Aug 2022 at 21:29, Yann Vernier ***@***.***> wrote: Can't we simply use the docbook backend because it still supports index generation? — Reply to this email directly, view it on GitHub <#468 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAY34O5TX7GU7MWHILW4AITV2ZZY7ANCNFSM56XKU4AA> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[lonetech]

I've only really tried the one (asciidoctor+xmlto in Debian) and am not sure what issues you've encountered. I'm also rather tired for today and getting sidetracked by dictionary considerations.

[jkotlinski]

asciidoctor+xmlto setup mostly worked, but I could not figure out how to make version information look as good as with pure asciidoctor. Also, I could not get preamble to appear above toc.

asciidoctor-multipage seemed promising, but had other annoying toc bugs

[lonetech]

I found one way to move information up above ToC, by putting it in pass-through <info><abstract> tags. Hacky. Beside that it's basically stylesheets, and I haven't dug into it. Despite how much wider utility fixing the asciidoctor issues would have, I seem more enticed to mull over durexforth details.

[jkotlinski]

I think it is fine to simply wait for asciidoctor/asciidoctor-multipage to improve! These problems will solve themselves in time.