Re: Man pages Was RE: Structure for GUI & Command Line Input Doc

[Sandy Harris <pashley -at- storm -dot- ca>]

"Stevenson, Rebecca" wrote:
> 
> Coincidentally enough, as this email crossed 
> my threshold yesterday our doc team was
> approached by engineering and asked if we
> were planning to distribute our doc in man
> page form ...
> 
> It had never crossed my mind to do this.
> I don't have the foggiest idea *how* to do this.

I'll comment below.

> And yes, I am appropriately ashamed of my UNIX
> ignorance.

A minor usage point here. See list archive for a
previous discussion.

It was originally "Unics", a bit of wordplay on
"Multics", but was "Unix" by the mid-70s when it
started to spread. AT&T decreed that "UNIX" was
the correct spelling when they began marketing
it heavily, early 80s.

Old hackers still use "Unix"; most people today
use "UNIX". Which you should use likely depends
both on your audience and the image you want to
project. It may also depend on legalities since
it was the trademark holder who decreed "UNIX".

> Our product is browser-based; it doesn't have
> a CLI. Does it even make sense for engineering
> to ask us to provide installation instructions
> as man pages,

I'm an old Unix user, a bit of a curmugeon on this
topic. My opinion may not match either engineers
or audience. I want a man page for everything I 
can see.

If I start your program by typing "foo" on a 
command line or putting "foo" in some script,
then "man foo" should print something. It may
only tell me the version number and where to
find the PDF or HTML docs, but it should be
there.

If there's a separate program foo-admin, then
"man foo-admin" should work too. It may point
to the same man page as "man foo", but it
should produce a result.

Most important, if your program is controlled
by a configuration file /etc/foo.conf, then I
want a section 5 man page for that file. Here
I have a strong preference for a real man page,
with actual detailed description of the file
format. I'll grumble if you just point to the
HTML or PDF. This isn't entirely me being a
curmugeon; I may need to fiddle with the file
to fix a crashed system and it is hard to read
PDFs when nothing works.

> and if so, what would be involved in
> translating our Frame files to this format?

My previous message had:

> Traditionally, everything on a Unix system -- user
> commands, file formats, admin commands, programmers'
> libraries, ... -- must have a man page. These are
> accessible on-line, printable by the user (also often
> provided in book format by the vendor) and have a
> cross-reference system.

Historically, these were done using the Unix nroff or
troff text formatting utilities (new roff and
typesetter roff, descendants of Unix roff and DEC
runoff), plus a macro package for the man page format.

You can still do that, perhaps using groff (GNU roff,
found in any Linux or *BSD), but you don't want to if
you can possibly avoid it!

This stuff was pretty good in its day, and does
still work, but runoff was a 1960s design, nroff and
troff early 70s. The macro packages were never
remarkably easy to use, and by today's standards are
distinctly painful, even if you already know them.

One alternative would be to use the DocBook SGML or
XML DTD. See www.docbook.org. This includes a full
set of tags for man pages, which it calls "reference
sections". I presume it can be made to work with
Frame+SGML, but don't know details.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Free copy of ARTS PDF Tools when you register for the PDF
Conference by April 30. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com

Are you using Doc-to-Help or ForeHelp? Switch to RoboHelp for Word for $249
or to RoboHelp Office for only $499. Get the PC Magazine five-star rated
Help authoring tool for less! Go to http://www.ehelp.com/techwr

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.