Re: [Firebird-docs] Man page for isql finished

[David J. <dav...@di...>]

Personally I like writing documentation in docbook xml (using emacs +
psgml) and compiling to html and pdf.  Are man pages still usually produced
for new unix projects, rather than relying on eg html docs?  Do you have
any links to sgml to man page tools?  The rudimentary manual stuff I
committed long long ago is based on this xml docbook to html and pdf plan.

david jencks

On 2002.04.11 15:13:04 -0400 Gerhardus Geldenhuis wrote:
> Hi
> At long last the first page is finished. Writing man pages is a black art
> one which I have not yet mastered. Please give comment about the page if
> you
> dont mind. If you only want to view it you can use the following command:
> $groff -man -Tascii ./isql.1 | less which should show you the page
> formatted. There is examples in the examples section which I simply could
> not get to display correctly. Writing this man page has caused me to some
> research and this has brought up a few issues. Firstly in Linux most
> documentation is done in sgml and then converted to other appropriate
> formats. Because sgml is contents based it is much easier to write
> documentation and other people can consentrate on the conversion to
> pdf/man/docbook/etc. What is your opinion about sgml and how is the
> documentation currently structured and done?
> 
> I have inserted my name as the assembler of the man page. I took most of
> the
> information out of the Operations Guide but I dont know who the author is
> so
> I could not include that information in the man page.
> 
> I placed the man page in sector one which is:
> User commands that may be started by everyone.
> 
> There is definitely place for a whole lot more man pages and I personally
> feel that it should be included with all the unix-based installations as
> standard.
> 
> Linux has a file system standard that describes how man pages must be
> named
> in the case of multiple version in different languages. I dont know if we
> should follow that standard but we must definitely follow the POSIX
> 1003.1
> standard which describes the locale indentification string.
> 
> Lastly this man page is definitely still in beta until otherwise decided.
> 
> 
> Groete
> Gerhardus
>