Opened 3 years ago

Last modified 9 months 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:


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 , 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 (12)

comment:1 Changed 3 years ago by boklm

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

comment:2 Changed 3 years 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 3 years ago by catalyst

Cc: catalyst added

comment:4 Changed 3 years ago by atagar

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

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

comment:5 Changed 3 years 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 2 years ago by arma

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

comment:7 Changed 2 years 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 11 months 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 11 months ago by catalyst

Keywords: documentation manpage added

comment:10 Changed 11 months ago by catalyst

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

comment:11 Changed 9 months ago by swati

Asciidoctor, an implementation of the AsciiDoc processor written in Ruby, is a drop-in replacement for AsciiDoc in most cases. Asciidoctor provides a command-line tool and a Ruby API for converting AsciiDoc documents to many formats including HTML, PDF, EPUB, DocBook and man page. This tool is called the Asciidoctor toolchain.

You can read more here:

comment:12 in reply to:  6 Changed 9 months ago by cypherpunks

Replying to arma:

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

It looks like that's mdbook, which uses the pulldown-cmark crate for parsing.

(There's also rustdoc in the compiler itself, but that's specific to generating documentation for Rust code.)

Note: See TracTickets for help on using tickets.