Subversion is used on far more platforms than that have a default 'man'
support. Breaking support for Windows, OS/2 and Netware is not an
option.
So we need a canonical format that is different than one that isn't
platform dependent or requires more optional dependencies.
Bert From: James K. Lowden
Sent: 08/08/2013 02:13
To: Daniel Shahaf
Cc: dev_at_subversion.apache.org
Subject: Re: man pages for Subversion
On Wed, 7 Aug 2013 12:45:36 +0300
Daniel Shahaf <danielsh_at_elego.de> wrote:
> Then individual sections were edited by hand, sometimes to
> > put finishing touches on the formatting, sometimes to clarify the
> > text.
>
> How can we incorporate that into the dev cycle?
>
> if manual tweaks are required, we would have to follow a scheme
> similar to translations: the master English output
> (subversion/svn/svn.c:svn_cl__cmd_table) is updated, and afterwards
> someone comes along, regenerates the manpage, re-applies the manual
> edits, and commits. The problem is that a release may happen before
> someone gets to update the semi-manually-generated man pages, which
> will cause them to be out-of-date (with respect to 'svn help' output)
> in the release.
>
> So, in addition to Stefan's point about incorporating your man pages
> into the build system, I think it'll be useful to eliminate the need
> for manual steps.
First of all, let me say thanks for the positive response from
everyone, and thanks for asking. :-) I wasn't sure how my message
would be received, and I'm gratified I wasn't wasting my time.
It seems we agree having man pages would be a good thing; the next
question is how to keep them up to date. If we can agree on how to do
that, I'm willing to make changes that make the documentation more
amenable to the build system.
I suggest the following:
1. Keep the man pages in mdoc format as the "souce code".
2. Convert "svn foo --help" and "svn help foo" to invoke man(1), as
git does. Or use groff to generate plain text for static inclusion in
the the binary.
3. Add a cross-reference section to each page.
4. Consider keeping the manual as PDFs on the website. If you do, add
PDF escapes to the mdoc text to generate hyperlinks. (That's a
feature of groff nowadays.)
5. Consider a table of contents and an index.
If HTML is desired, there are a couple of options. I haven't used it,
but troff2page sounds nice.
http://www.ccs.neu.edu/home/dorai/troff2page/index.html#node_toc_start
GNU troff also supports HTML output, but I haven't had great luck with
it.
My manualize script is just a throwaway hack; it was easier (probably)
to parse the help output to generate the synopsis and option lists.
Going forward, it's probably not worthwhile to try to maintain a
database of options keyed by subcommand or whatever. Although the
synopsis and command-specific options are slightly redundant, keeping
them up to date and consistent won't be that much work. Subversion
doesn't change all that much at that level.
Contrary to popular wisdom, good old troff is the best system there is
for maintaining documentation. It's the least typing and the least
processing: the macros are just a few characters, and "processing"
mostly consists of copying the files to somewhere man(1) will find
them.
I say that having tried others: I used Doxygen and DocBook, and even
text2man. Troff is ugly, sure; Brian Kernighan called the syntax
"rebarbative". At the end of the day, though, you have to type
*something* to indicate "this is a list" and "this is an optional
function that takes an argument". mdoc is made for that, and it's
about 10% the size of e.g. DocBook, no matter how measured.
I'm completely sympathetic to the isssue of keeping the documentation
up to date. I've maintained the FreeTDS user guide for 10 years.
There's really nothing for it except to update as you go along, and to
review it (over and over) prior to release.
I confess I don't know how the Subversion source code is organized. IMO
the best place to keep documentation is in the source file directory.
I learned that trick from Dennis Ritchie. ;-)
Some of the text is shared between pages. To generate my drafts, I
just let ./manualize crank away. If mdoc is the canonical source, then
common text goes in a shared file. (There's really no need to assemble
the fragments; troff supports a ".so" directive that works like
#include in C.)
So: unless you already have a database of options somewhere, I'd
suggest maintaining the docs in mdoc format. If you like that idea,
I'm willing to make it easy. I would:
1. regenerate them using the HEAD version (or take the output from
someone who's currently hacking on it)
2. fix up the text some more
3. remove the shared text to shared files
4. add SEE ALSO cross references
5. deliver mdoc files and a GNU Makefile that with targets "install"
and "pdf"
More than that I won't promise, but we can discuss it. :-)
To deal with the copyright issue, I would put "Donated to the
Subversion project by James K. Lowden" or similar in each file in the
Authors section.
Happy to be of service. Let me know your thoughts.
Regards,
--jkl
Received on 2013-08-08 04:14:46 CEST