Re: Language Reference Guide

["Frank Ch. Eigler" <fche at redhat dot com>]

Hi -

On Thu, Oct 19, 2006 at 02:59:13PM -0500, Robb Romans wrote:
> [...]
> > Perhaps it would be appropriate to expand or reorganize the man page
> > [...]

> Thank you for the suggestion. I'm only a writer, tasked by my customer 
> (IBM RAS Team). I can't speak for them, but it's my understanding that 
> they felt a Language Reference Guide would fill a need more easily met 
> by a separate document in a publication format, rather than a man page. 

I guess it's neither here nor there for me.  I would like to retain a
good ASCII (man or perhaps texinfo) form as an installed reference.  I
would like to have a web/printworthy tutorial.  I would like to have a
bank of examples that are easily cut & pasted or run directly.
Whatever accomplishes these requirements without too much effort (too
many different documentation sources & formats to keep up-to-date),
that's fine.

I would like you to keep in mind though that, for each new nugget of
text you write, whether that same nugget would also find a good home
in one or the other existing document.  In other words, if some
particular sentence that explains "foreach" can improve the man page
and/or the tutorial, as well as the new derivative, then please do put
it in all the places.  If you end up with just a number of small
incremental changes, you might find there may be little need for a new
document in the end.


> As I stated in the OP, existing documentation (such as the man page) 
> will be the source of information going into the Lang. Ref. That can be 
> clearly attributed in a bibliography if you like.

Sure.

> By the way, what tool do you mention above to easily convert to/from
> man format? I haven't found one and would like to try it.

man (as a part of nroff) can be directly processed by standard nroff
tools to rendered formats such as ascii, html, and pdf.  Conversion to
another markup form is, as one might expect, more involved.

- FChE

Attachment: pgp00000.pgp
Description: PGP signature