Man page update

• 2005-10-23 A lot of little fixes were made. New man pages were committed to CVS.
• 2004-09-02 Every non-documented option has been identified, and work can now begin on completing the descriptions.

I'm working on this now, the manpages need to be converted from DSSL to XSL, I've got most of the work done, it's just a matter of sorting the nitty build bits and making it easier to commit back up to the src repo.

After I'm done the doc backend conversion I'll go back in and fill in all the bits that need documenting.

Along with fixing the language of the manpages, we need to add examples into each one (this was previously a seperate ticket)

One important bit that should be logged here, is trolling through the documentation and removing any internal references to tendra options. These should be either removed or merged into the manpages with references updated in the document to the manpages themselves. Since our manpages are XML we have the luxury of including them into our pdf/html/text outputs. Rather than trying to keep both synced (which we all know won't happen) it's better to refer to the manpages.

For a while now I've hated how our current manpages are, they're inconsistant, poorly worded and lack relevant information for real-world usage, so here's my master plan:

My goal is to make every manpage uniform and supply the relevant information for the beginner TenDRA user to fully use our tools and tcc without any issues.

Breaking up the main tool manpages is easy, we'll keep the regular layout for most tools the same:

• NAME
• SYNOPSIS
• DESCRIPTION
• OPTIONS
• <any tool specific headings/explanations go here>
• EXAMPLES (example usage.)
• ENVIRONMENT (any environment variables that are adhered to)
• EXTENSIONS (filename extensions, if required)
• EXIST STATUS (list codes, or just a note about 0 >0 errors)
• COMPATABILITY (if required)
• STANDARDS (if required)
• HISTORY (if required)
• BUGS (too many too list here? hehe))

Now, the translator pages are going to be tricky, I want to split the options and sections up so it makes more sense visually and it makes life easier for us to maintain.

Keep in mind that any sections not mentioned here fall into the above layout.

DESCRIPTION

• Description - common across all translators
• <thistrans> - this translator
• <arch> Descr - common across <arch>
• <os> Descr - common across <os>

OPTIONS

• General - all translators
• <thistranslator> - options specific to <thistranslator>
• <arch> - common across all <arch> translators
• <oshere> - common across all <oshere>

You get the idea, rather than mashing everything together and making it confusing it's better to let our users know what options will carry, and what expected behavior exists across platforms. It's far better than jumbling all the options and information together so you have no idea where one arch/os ends and another starts.

The tcc manpage will be it's own beast, it doesn't fall into any of the other tools so rather than fumble around trying to create the 'best layout' I figured stealing from the gcc manpage would work, they use this sort of layout:

• NAME
• SYNOPSIS
• DESCRIPTION
• OPTIONS
• FreeBSD SPECIFIC OPTIONS
• OVERALL OPTIONS
• LANGUAGE OPTIONS
• PREPROCESSOR OPTIONS
• ASSEMBLER OPTION
• LINKER OPTIONS
• DIRECTORY OPTIONS
• WARNING OPTIONS
• DEBUGGING OPTIONS
• OPTIMIZATION OPTIONS
• TARGET OPTIONS
• MACHINE DEPENDENT OPTIONS
• CODE GENERATION OPTIONS
• PRAGMAS
• FILES
• SEE ALSO
• BUGS

I pretty much had all of these planned anyway, but for the sake of sanity it may be good to have ours layed out in a similar fashion. Of course not all of these will apply.

If you've got any input or comments just attach it to this ticket, thanks!