[Groff] Documenting the Source. (Was: Overview, Sept. 2014)

[Ralph Corderoy]

Hi,

Ulrich wrote:
> As I understand it, the man-pages are directed at the user of a
> program who wants to know WHAT a program is supposed to do and how she
> can control it via options.
> 
> Comments in the source are directed at the programmer, who wants to
> understand HOW the functionality of the program is accomplished.

I don't think it's that simple.  man pages include file formats, special
files, e.g. devices, and a catch-all miscellaneous, section 7, where
much groff stuff hangs out.

I've certainly seen program internals documented in man pages;  not
section 1 or 8, but a specific `internals' man page.  perlguts(1) for
example, divulges a lot of the higher-level internals to make it easier
to read the source.  I've written foodev(7) to accompany foo(1) several
times over the years, outlining the internal structure of the program
and how it fits together.  (Bell Labs used to release papers alongside
the man pages, but that was more to introduce novel programs, e.g. yacc,
than explain their source.)

I agree, inline comments are needed on a localised basis, before a
non-obvious bit of code say, and in particular I find it handy to
comment data since the code that describes its use can be scattered.
And that seems to be the case on the first file I picked on:
http://git.savannah.gnu.org/cgit/groff.git/tree/src/roff/troff/input.cpp#n109

I think what's missing is a higher-level view of how the source fits
together, and that's probably why Werner's enthusiastic about a
comment-block per class.  Without an overview, reading the source tends
to be bottom-up;  one pieces together enough fragments to recognise a
section of the puzzle.  With it, you've a rough idea what piece belongs
where even if you haven't found it's exact spot yet.

Perhaps those on the list that can grok C could have a go at doing
Werner's class comments, just as we re-set O'Reilly's _Unix Text
Processing_ book.  But would it require copyright assignment?  That's
been a stumbling block for me in the past.  Mind you, Bradley M. Kuhn,
an FSF board member, wrote
http://ebb.org/bkuhn/blog/2014/06/09/do-not-need-cla.html so perhaps
there's movement there.  :-)

Cheers, Ralph.