On Wed, 7 Aug 2013 12:45:36 +0300 Daniel Shahaf <danie...@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