FS#7312 - Use asciidoc to generate man pages.

Attached to Project: Pacman
Opened by Andrew Fyfe (space-m0nkey) - Wednesday, 30 May 2007, 20:42 GMT
Last edited by Dan McGee (toofishes) - Wednesday, 14 November 2007, 22:45 GMT
Task Type Feature Request
Category Documentation
Status Closed
Assigned To Dan McGee (toofishes)
Architecture All
Severity Low
Priority Normal
Reported Version 3.0.4
Due in Version 3.1.0
Due Date Undecided
Percent Complete 100%
Votes 1
Private No

Details

At the moment the man pages are a PITA to maintain. I propose switching to asciidoc to generate the man pages, it'll also generate the html version.

pacman.8.txt: This is the source file the devs will maintain, it's clear any easy to maintain with minimal markup required.

paacman.8, pacman.8.html: The files generated by asciidoc.
This task depends upon

This task blocks these from closing
 FS#8109 - Pacman 3.1 Release Roadmap 
Closed by  Dan McGee (toofishes)
Wednesday, 14 November 2007, 22:45 GMT
Reason for closing:  Implemented
Additional comments about closing:  Implemented in GIT
Comment by Dan McGee (toofishes) - Saturday, 30 June 2007, 14:57 GMT
I like this, sorry I'm late on really looking it over. Now to spew some stuff:
1. Having the options be bolded would probably be nice, like they are in the current manpage.
2. We should combine the parts of both of your (Andrew) doc branches at the moment. Put all of these text files in at pacman.8.txt.in type names, and then we'll write a Makefile rule just like we did for the scripts/ and etc/ directories. I want to do this so we can do variable substitution of such things as versions and even the package name, if possible. Basically the things I had in the variables from before, but we can just do them at compile time instead of run time.

I'll start my own little asciidoc branch and see if I can't get the make rules set up right. However, it looks like you have a good start going on making the txt files themselves, so I'll let you do that. Try to keep the line wrap at 80 on all of them if possible.
Comment by Dan McGee (toofishes) - Saturday, 30 June 2007, 15:54 GMT
What command did you use to go from txt file to manpage? I can't figure it out, although I do have some makefile rules working almost correctly.
Comment by Andrew Fyfe (space-m0nkey) - Saturday, 30 June 2007, 16:54 GMT
a2x -d manpage -f manpage --asciidoc-opts="-f asciidoc.conf -apacman_version=3.1.0-dev"

This is the command I use for the asciidoc branch, asciidoc.conf was borrowed from git. They use asciidoc for all their documentation so it's a good place to look for how to use asciidoc.

Loading...