Opened 22 months ago

Last modified 6 weeks ago

#25519 new task

move away from asciidoc

Reported by: dkg Owned by:
Priority: Medium Milestone: Tor: unspecified
Component: Core Tor/Tor Version:
Severity: Normal Keywords: 035-removed-20180711, documentation, manpage
Cc: boklm, catalyst Actual Points:
Parent ID: Points:
Reviewer: Sponsor:

Description

asciidoc is the only part of the tor build process that requires python 2. python 2 is deprecated upstream and is approaching end-of-life.

Over in https://bugs.debian.org/892830 , i asked about upgrading asciidoc to move to python3, but apparently asciidoc itself is on life support, and upstream is encouraging everyone to move to asciidoctor instead (which introduces a ruby dependency) or to use something else like pandoc.

in any case, presumably we want the documentation to stay buildable, so i encourage switching away from asciidoc.

Child Tickets

Change History (10)

comment:1 Changed 22 months ago by boklm

Cc: boklm added
Component: - Select a componentCore Tor/Tor

comment:2 Changed 22 months ago by nickm

Milestone: Tor: 0.3.5.x-final

Makes sense to me. Is there anything that consumes markdown and produces good manpages nowadays? The reason we went with asciidoc originally was that it produced better roff than the other tools we had around, and it didn't force us to learn sgml.

comment:3 Changed 22 months ago by catalyst

Cc: catalyst added

comment:4 Changed 22 months ago by atagar

Hi Nick, for what it's worth another option is reStructuredText. Sphinx generates html, man docs, and others...

http://www.sphinx-doc.org/en/master/rest.html
http://www.sphinx-doc.org/en/stable/man/sphinx-build.html

This is what Stem and Nyx uses to generate their docs.

comment:5 Changed 22 months ago by catalyst

From having used Sphinx elsewhere, I know its manpage output at least used to rely on groff features, so wouldn't work on plain nroff/troff. Maybe we don't care, but it's something to be aware of.

comment:6 Changed 20 months ago by arma

At the network team meeting people mentioned markdown, or also whatever-rust-uses-for-markdown.

comment:7 Changed 19 months ago by nickm

Keywords: 035-removed-20180711 added
Milestone: Tor: 0.3.5.x-finalTor: unspecified

These tickets are being triaged out of 0.3.5. The ones marked "035-roadmap-proposed" may return.

comment:8 Changed 6 weeks ago by catalyst

Asciidoc's successor appears to be Asciidoctor. Unfortunately there seem to be some tools out there that claim to support Asciidoc but really support Asciidoctor and don't have full Asciidoc support. There are some nontrivial differences in the syntax.

We discovered this during some Google Season of Docs work, when we noticed that the Asciidoc preview and editing plugins for the Atom editor actually support Asciidoctor rather than Asciidoc. This led to some divergence of expectations about what the rendered output would look like.

Does anyone know of a reason we should not migrate to Asciidoctor at some point? It seems less troublesome than migrating to a completely different kind of markdown.

comment:9 Changed 6 weeks ago by catalyst

Keywords: documentation manpage added

comment:10 Changed 6 weeks ago by catalyst

For additional annoyance, it looks like Asciidoctor swapped monospace and verbatim markup from legacy asciidoc?

Note: See TracTickets for help on using tickets.