[syslinux] Syslinux docs for core variants and installers

Gene Cumm gene.cumm at gmail.com
Tue Nov 13 16:36:45 PST 2012


Yet another round of questions:

- Should the text documents I'm editing, formatted for AsciiDoc be the
preferred human-readable format or would the output of 'a2x -f text'
be suitable?  The AsciiDoc-formatted file will have a small amount of
markup in it (ie "*SYSLINUX*", "*LINUX* 'image'::", or
"include::com-bug.txt[]") while the text output will be cleaner and
all-inclusive.

- Should the filenames be simple, compressed or follow reasonable
rules for man pages?  ie, config.txt, syslxcfg.txt or syslinux.cfg.txt
with a title "syslinux.cfg(5)".  Git (the project) uses the latter as
it helps with forming not only man pages but links between the
documents in at least some HTML rendered samples.  Compressed
(syslxcfg.txt) would fit 8.3 rules which are already broken in
numerous other filenames.  Simple names are easy to read but won't
reflect the manpage output names.

- Should paragraph indentation or block delimiters be used?
Indentation results in "literal paragraph" style whereas delimited
could be as a ListingBlock (friendlier output for code listings) or
LiteralBlock.

-- 
-Gene



More information about the Syslinux mailing list