Opened 20 months ago

Last modified 16 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
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 (7)

comment:1 Changed 20 months ago by boklm

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

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

Cc: catalyst added

comment:4 Changed 19 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 19 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 17 months ago by arma

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

comment:7 Changed 16 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.

Note: See TracTickets for help on using tickets.