Opened 3 years ago

Closed 2 years ago

#10342 closed task (fixed)

Convert User Guide from DocBook to AsciiDoc

Reported by: dmbergey Owned by: dmbergey
Priority: normal Milestone: 8.0.1
Component: Documentation Version: 7.10.1
Keywords: Cc:
Operating System: Unknown/Multiple Architecture: Unknown/Multiple
Type of failure: Documentation bug Test Case:
Blocked By: Blocking:
Related Tickets: Differential Rev(s):
Wiki Page:

Description

See initial proposal and discussion on the mailing list: https://mail.haskell.org/pipermail/ghc-devs/2014-October/006599.html

and the more recent call for volunteers: https://ghc.haskell.org/trac/ghc/blog/weekly20150414

Quoting the latter: the idea [is] that it will A) make life easier for people who frequently modify the users guide, and B) make life easier for people who add things irregularly, as a lower barrier to entry.

I expect that asciidoc & DocBook can coexist while I work on this. After the initial changes to the build system, the docbook-to-HTML phase should read both the asciidoc-generated XML and the not-yet-converted XML files.

This ticket will track progress on the task, as I plan to submit multiple patches, perhaps as many as one per file converted.

Change History (5)

comment:1 Changed 2 years ago by thomie

Type of failure: None/UnknownDocumentation bug

comment:2 Changed 2 years ago by bgamari

I have looked into this in the past and found that asciidoc has a few rough edges that make a proper conversion of the users guide rather ugly. I recently tried a conversion to ReStructuredText and was happy to find that a mostly mechanical conversion got quite far.

I've proposed moving to ReStructuredText in https://mail.haskell.org/pipermail/ghc-devs/2015-September/010001.html this mailing list thread (which references my preliminary conversion).

Last edited 2 years ago by bgamari (previous) (diff)

comment:3 Changed 2 years ago by bgamari

I have started a page to describe this change.

comment:4 Changed 2 years ago by thomie

Don't forget to update utils/mkUserGuidePart.

comment:5 Changed 2 years ago by thomie

Milestone: 8.0.1
Resolution: fixed
Status: newclosed

In 4fd6207ec6960c429e6a1bcbe0282f625010f52a:

Author: Ben Gamari <>
Date:   Thu Oct 1 01:08:41 2015 +0200

    Move user's guide to ReStructuredText
Note: See TracTickets for help on using tickets.