[syslinux] Syslinux docs for core variants and installers

[Gene Cumm]

On Tue, Nov 13, 2012 at 10:35 PM, H. Peter Anvin <hpa at zytor.com> wrote:
> 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.

Agreed.  AsciiDoc lends itself to being naturally lighter in markup.
It's more the "just enough" versus "moderate" direction.  ie, using
"*SYSLINUX*" to make bold/emphasized text for most/all occurrences.

I do still need to redo word wrap on the documents before submission.

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

My inclination is manpage-style.  One reason is that it could lend
itself to helping with creating the links between different HTML
documents, reducing how much needs to be altered for import.

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

== As Indent ==
- Make a DOS-bootable disk;  The following are possible commands:

	format a: /s
	sys a:

*ONERROR* 'kernel options...'::
ON error ... reads as:
	ONERROR xyzzy plugh


== As block ==
- Make a DOS-bootable disk;  The following are possible commands:
+
....
format a: /s
sys a:
....

*ONERROR* 'kernel options...'::
ON error ... reads as:
+
----
ONERROR xyzzy plugh
----

-- 
-Gene