🚀 go-pugleaf

>[Issues of how to distribute and document software are not really topical,
> but they do apply to many C programmers, and one of the advantages of a
> low-traffic newsgroup is that we can have topic drift without losing
> completely. -mod]


Let me repeat a point I made earlier:

	[c2man is] a program [by Graham Stony of Canon Information Systems
	Research Australia] for generating Unix style manual pages in
	nroff/troff -man, TeXinfo, LaTeX or HTML format directly from
	ordinary comments embedded in C source code.  It should run on
	virtually any Unix-like system, OS/2, VMS, MSDOS or Amiga systems.

I find that I have three problems with UNIX manual pages:

    - the viewer won't let you move _back_ in a document

    - there is hypertext structure in the documents (SEE ALSO) but the
      viewer is unable to exploit it

    - the markup language used for the documents is so arcane that I have
      never yet found a UNIX on-line manual set without embarrassing
      formatting errors.

I find that there are several problems with TexInfo documents:

    - they are way too big and hard to navigate around; I can only use
      them effectively if I already have a printed copy

    - for most people, 'info', if they have heard of it at all, is a
      clunky brute that is useful for nothing else.  In fact, when I
      try to use it, something goes wrong, so obviously there was an
      installation problem and no-one has noticed because no-one uses it.

    - the markup language used for the documents is a TeX macro package,
      which is a bit easier to use than nroff, but not a whole lot, and
      worse still, the macros change from time to time...

To borrow a phrase from an H.P.Lovecraft story, "The way out is to go UP".

Is there a format for which viewers are available on many platforms, not
just UNIX?
Is there a format which is usable with character terminals, but can take
advantage of GUI screens?
Is there a format which supports hypertext simply and well?
Yes there is:  HTML.

Is there any way we can generate documentation for C code
_without_ learning some arcane markup language,
_without_ committing to any particular viewer,
_without_ sacrificing the possibility of nicely printed documents,
_without_ sacrificing backwards compatibility with existing 'man'
    or 'TexInfo' document collections?
Yes there is:  c2man.

The implementation of c2man is tied to C, and has its limitations,
but the _idea_ is general.

-- 
The election is over, and Australia lost; the idjits elected _politicians_!
Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.