[svlug] non-graphical documentation in man, texinfo, text, html, etc., formats

Karsten M. Self kmself at ix.netcom.com
Tue Mar 18 12:05:18 PST 2003


on Tue, Mar 18, 2003 at 10:35:09AM -0800, dpchrist at inreach.com (dpchrist at inreach.com) wrote:
> svlug at lists.svlug.org:
> 
> I want to write some non-graphical documentation that will end up in
> man, texinfo, text, html, and possibly other formats.  

Some of these are not proper intersections.  E.g.:  man and texinfo are
fundamentally different documentation types, each with an uderlying doc
format (groff and texinfo, respectively.  I'd suggest that info be
strongly deprecated in favor of DocBook or HOWTO-style documentation.
No, let's change that.  I'll publicly ridicule you for doing an Info
page:

    http://twiki.iwethey.org/twiki/bin/view/Main/InfoVsManpage

In this case, your situation reduces to manpage + everything else.

Note that manpages themselves can be presented as text (via groff and
col), PS (also groff), PDF (vi groff and psutils), HTML (via dwww).
This may be a sufficient solution for you.

Otherwise:  hie thee to (X)Emacs and psgml tools and start DocBooking
away.

If you want a simpler markup language, LaTeX, as suggested, may fit the
bill.  IMO DocBook is somewhat overspecified, but as may suit your
needs, it's overspecified in the direction of producing technical
documentation.

Once you've got your source document format(s), then yes, using a
makefile to produce variants is trivial.  I actually use a mix of
makefiles, foo.d directories (in which components of a file sit as
separate files in a directory), and child subdirectories with either
links or local variants of the parent foo.d directory, to maintain my
resume in a dozen or so variations, and five file formats.  It's
convenient to be able to "compile" your resume ;-)

Peace.

-- 
Karsten M. Self <kmself at ix.netcom.com>        http://kmself.home.netcom.com/
 What Part of "Gestalt" don't you understand?
    First they came for the Communists, and I didn't speak up, because I
    wasn't a Communist.  Then they came for the Jews, and I didn't speak
    up, because I wasn't a Jew.  Then they came for the Catholics, and I
    didn't speak up, because I was a Protestant.  Then they came for me,
    and by that time there was no one left to speak up for me.
    -- Rev. Martin Niemoller, 1945



More information about the svlug mailing list