Re: [Groff] man pages for macro packages

[Bernd Warken]

On Tue, Nov 27, 2001 at 01:44:26PM -0800, Redman Jack wrote:
> A better
> solution would be a good tutorial to help get newbies
> up and running with one of the macros.  Since many
> newbies are probably looking at groff as a potential
> way of inserting illusration (photos, drawings and
> such) into their documents, the use of the PSPIC macro
> should be included (including the correct ways of
> generating the eps file needed.)  
> 
Writing a documentation is the best way to learn about a program,
so you are welcome :-)

On the PSPIC macro, some questions to the developers.
- Where should PSPIC be documented?  I wouldn't want to start another 
  man-page.
- pspic.tmac is included by the tmacs X, html, ps, but not by dvi and 
  the text devices.  This forces the user to write conditional code.
- Can pspic go to the new tmac `device' subdirectory?

> Also, changing the names could lead to confusion even
> without a clash.  For instance, groff_man(7) is
> obviously a groff man page but man(7) may or may not
> be a groff man page.  It might be related to the
> man(1) man page.  And if someone types 
> 
>     # man man
> 
> he would most likely get man(1) and not man(7) if
> groff_man(7) were renamed to man(7).  

You are absolutely right.  man(7) is obsessed anyway.

A similar situation exists with groff(7).  Maybe it should be renamed to
groff_language(7) and some parts from it and from roff(7) should
be moved to groff(1).

> Another thing to keep in mind is the gui help systems
> such as the Gnome Help Browser.  The Gnome Help lists
> things alphabetically and not by directories so you
> get groff(1) but not groff(7).  The naming scheme of
> groff_* and gro* also keep all of the groff man pages
> together in an alphabetical listing.  
> 
The help browsers are section based, so you won't get all in one chunk.
I think it will be easier to find a macro man-page if these all start
with tmac_* instead of being mixed with the language groff_* man-pages
once you are used to it.

> And now for a question.  The groff_me man page's SEE
> ALSO section gives a reference for the "-me Reference
> Manual by Eric P. Allman" and for "Writing Papers with
> Groff Using -me."  Does any body know where I can find
> these references.  Especially the manual.  Thank you. 
>   
You can find them in the ./doc subdirectory of the groff source package.
There are 2 files, meintro.me and meref.me.
You can read them e.g. with the shell command

groff -me -TX100 meintro.me | gxditview

or

groff -me -Tlatin1 meref.me | less

Unfortunately, they are not installed by default.  I think we should
make them installed
1) as .me with a README how to read them and a shell script for xdit'ing
2) as .html's with an index.html
3) maybe all man-pages and the info file should be html'ed as well
4) it could be good to put all of these extra documents in a package of
   its own, groff_doc.

Bernd Warken