[syslinux] Syslinux docs for core variants and installers

[H. Peter Anvin]

On 11/13/2012 04:36 PM, Gene Cumm wrote:
> 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.
>

Well, they should be *readable*, but for actual text output a2x -f text 
is fine.

> - 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.

I don't care about 8.3 anymore... I don't think anyone else does, either.

> - 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.

Not sure what you are asking here...

	-hpa


-- 
H. Peter Anvin, Intel Open Source Technology Center
I work for Intel.  I don't speak on their behalf.