[csw-maintainers] ITP: opencsw-policy

[Ben Walton]

Excerpts from Peter FELECAN's message of Fri Dec 31 06:20:24 -0500 2010:

> IMO, LaTeX is less about backslashes than document format and good
> typography. Other than using macros you don't need a lot of special
> characters...

We converted our documentation at work from texinfo to docbook as
people didn't like the idiosyncrasies of texinfo (not strictly LaTex,
of course).  Emacs makes editting the xml easy as it does most of the
work and I'm sure vim offers similar functionality.

I'd vote for docbook or asciidoc.  (I won't argue that LaTex produces
nicer output though. :))

Can I suggest that we not (necessarily) use subversion to handle the
the VCS needs of this though?  Git offers a 'notes' feature that would
be quite useful for something like this, I think.  The commit message
can describe the change that is made and then the change can be
annotated with a note that references the mailing list thread that
spurred the change.  It's meta-info about the commit.

I like this idea a lot.  While a package as the final output is
certainly nice, it's pretty heavy-weight.  Do you envision the
packaged files as the set of files that the website would display, or
just something that anyone could fetch to peruse?

At work, we share a git repository of our docbook formatted system
procedures and docs, etc.  On a push to the central repository, we
validate the xml and if it passes, automatically publish the changes
to a website where we reference it from.

Thanks
-Ben
--
Ben Walton
Systems Programmer - CHASS
University of Toronto
C:416.407.5610 | W:416.978.4302