FS#8105 - improve mkinitcpio documentation

Attached to Project: Arch Linux
Opened by Jens Adam (byte) - Sunday, 23 September 2007, 21:24 GMT
Last edited by Roman Kyrylych (Romashka) - Saturday, 09 February 2008, 18:33 GMT
Task Type Feature Request
Category Packages: Core
Status Closed
Assigned To Aaron Griffin (phrakture)
Thomas Bächler (brain0)
Architecture All
Severity Low
Priority Normal
Reported Version 2007.08.1
Due in Version Undecided
Due Date Undecided
Percent Complete 100%
Votes 0
Private No

Details

If you run it without arguments, it should output the help message.

It should show the help not only with -h, but with --help as well.

A manpage would be nice. (I wouldn't even mind proof-reading it :)
This task depends upon

Closed by  Roman Kyrylych (Romashka)
Saturday, 09 February 2008, 18:33 GMT
Reason for closing:  Implemented
Comment by Glenn Matthys (RedShift) - Sunday, 23 September 2007, 22:00 GMT
I've created a small first draft of a mkinitcpio manpage. You can find it here:

http://users.opengate.be/~glenn/arch/man-mkinitcpio.txt

Any comments, suggestions, additions, etc... are very welcome.
   man-mkinitcpio.txt (3.1 KiB)
Comment by Jens Adam (byte) - Sunday, 23 September 2007, 22:01 GMT
Okay, the first one isn't probably worth it, imo. But -h/--help would be cool.
Comment by Glenn Matthys (RedShift) - Sunday, 23 September 2007, 23:04 GMT
Hint, always check out the most recent version at:

http://users.opengate.be/~glenn/arch/man-mkinitcpio.txt

Current state is "almost finished". I think it looks pretty good and everything that should be explained, is explained. But I would still like the developer team to have a look at it and fill the gaps I might have made. After that it's just converting to latex and it's ready for inclusion in the mkinitcpio package.
Comment by Jens Adam (byte) - Monday, 24 September 2007, 02:40 GMT
Minor nitpick: the AUTHORS section; right now you might mistake 'our' names for the Arch Linux developer community that has created mkinitcpio. Better add a separate "Manpage authors/contributors:" or similar.
Comment by Glenn Matthys (RedShift) - Monday, 24 September 2007, 07:44 GMT
Fixed.
Comment by Glenn Matthys (RedShift) - Monday, 24 September 2007, 18:01 GMT
Ok, the manpage is done, you can find it here:

http://users.opengate.be/~glenn/arch/mkinitcpio.5.gz

this should be put in /usr/man/man5
Comment by Thomas Bächler (brain0) - Wednesday, 31 October 2007, 09:18 GMT
I am adding this manpage as-is now. However, could you give me the "source" of the manpage and tell me how you generated it?
Comment by Glenn Matthys (RedShift) - Wednesday, 31 October 2007, 09:55 GMT
The source can still be found here:

http://users.opengate.be/~glenn/arch/man-mkinitcpio.txt

the actual manpage is generated by txt2man.
Comment by Thomas Bächler (brain0) - Wednesday, 31 October 2007, 12:23 GMT
txt2man is in community, thus I shouldn't use it as a makedepend. Is there another tool doing the same?
Comment by Roman Kyrylych (Romashka) - Wednesday, 31 October 2007, 12:39 GMT
How about converting the source to the format used by asciidoc (which is already used by pacman)?
Comment by Aaron Griffin (phrakture) - Wednesday, 31 October 2007, 16:41 GMT
asciidoc is very much overkill here. Manpages do have a very simple markup that can be hand edited. pacman used hand-edited man pages for a LONG time.
Comment by Thomas Bächler (brain0) - Wednesday, 31 October 2007, 17:06 GMT
So you are saying that using txt2man is sufficient. Should we move it to extra then?
Comment by Aaron Griffin (phrakture) - Wednesday, 31 October 2007, 17:27 GMT
I was actually saying we should stick the uncompressed man page in there, and not the text file.

How about this. We add a 'dist' target to the Makefile that generates the man page with txt2man before making the tarball. This way it's not even a makedepend - pacman does the same thing with asciidoc.
Comment by Thomas Bächler (brain0) - Wednesday, 31 October 2007, 17:39 GMT
A make dist target is not as nice as using git-archive for generating tarballs. I'd rather generate the manpage at build/install time.
Comment by Aaron Griffin (phrakture) - Wednesday, 31 October 2007, 18:11 GMT
That sounds like a roundabout way to do it, but that's fine - just make sure you maintain txt2man then when you move it to extra.
Comment by Jens Adam (byte) - Saturday, 15 December 2007, 14:10 GMT
I'm considering having this one closed. Any objections or last considerations?
Comment by Glenn Matthys (RedShift) - Saturday, 15 December 2007, 14:13 GMT
Maybe someone can convert this into latex/manpage format?

Loading...