Single source documentation

["John R. Daily" <jo...@geekhavoc.com>]

Earlier this year, the problem of documentation duplication was
discussed on this list, but apparently nothing ever came of it.

This evening, I've been experimenting with a process to generate
the help command text from the refentries in the book, and I have
an alpha-quality solution.

I've created a relatively small XSL stylesheet that generates
roff output.  That output is then processed a bit more, run
through troff and grotty, and finally run through a Perl program.
The output is a C string for inclusion into the client program's
help structure.

(I used Perl because text processing in C is about as fun as
pulling teeth; any language would do.)

I'm attaching the XSL stylesheet and the Perl program.  The
pipeline looks something like the following.  Assuming that the
refentry for svn status has been extracted into svn-status.xml:

   > xsltproc refentry-to-cstring.xsl svn-status.xml | \
[1]    sed 's/^ *//' | \
[2]    sed "s/^'/ '/" | \
       troff -man -Tlatin1 | \
[3]    grotty -b -c | \
       cleanup-cstring.pl > svn-status.h

Notes:
1:  The only alternative to this that I can find is to edit the
    source XML so that character data is always flush left, like:

    <para>This is a rather
short paragraph.</para>

2:  ' in the first column of roff input is considered to be a
    command character.

3:  Don't perform the stupid ASCII tricks that groff likes to
    use for highlighting and underlining.


I am not at all a roff person, and I'm still relatively new at
XSL, particularly for generating text instead of XML, so there
may well be better ways to handle some of the above issues.

I'll also attach the svn status string as generated by the above
pipeline; that's one of the most complex help strings, so it's a
decent proof of concept.  I did remove the xref tags from the
refentry before processing.

There isn't a good way to handle <xref> tags.  I'm personally of
the opinion that refentries shouldn't use xref or link tags, so
that they can be meaningfully translated into man pages.

(I also believe that the refentries _should_ be processed to
generate individual man pages.  I always disliked searching
through the giant single man page for cvs.)

Another caveat: currently, only the Description refsect1 is
processed.  The current online help for svn status includes
examples, so that section should be processed too; looking at the
XML, there will need to be templates for at least screen and
warning added before that will work properly.

--
John R. Daily
<email><mailbox>john</mailbox><domain>geekhavoc.com</domain></email>

Re: Single source documentation

["C. Michael Pilato" <cm...@collab.net>]

Greg Hudson <gh...@MIT.EDU> writes:

> So, I'm -1 on generating the help command text from the book (if the
> book authors want to generate refentries from the help documentation,
> they can, but I think it would reduce the quality of the book).  It's
> more work to maintain duplicate documentation, but it yields better
> results, and many more people are going to read our documentation than
> write it.

Oh, geez.  I knew I shoulda been reading this thread.  I'm *so* -1 on
this as well.  

Thanks for weighing in Greg.  I'm not ashamed to admit that sometimes
that's all it takes to get me to pay attention to a thread. :-)

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: Single source documentation

["John R. Daily" <jo...@geekhavoc.com>]

At (time_t)757942953 Greg Hudson wrote:

> My experience is that consolidation of documentation often leads to
> inferior documentation in many of the places you look for it, because
> there are different standards of brevity, precision, and target audience
> in different areas of documentation.

The online help command already provides an abbreviated version
of the reference pages; the content is virtually identical
today.  What this would do is eliminate the duplication of effort
that leads to errors.

Documentation isn't all that different from software in this
regard; duplication is at best a necessary evil, and I'm trying
to remove the necessity.

Furthermore, thanks to the flexible nature of XML and XSL, the
reference pages can contain enough metadata to dictate what parts
are reused for the online help, so the reference pages can expand
without forcing the online help to also grow in length.

Heck, the reference pages could include content that is _only_
displayed in the online help, so the flexibility of having online
help be worded differently from the technical reference is
maintained.

> It also leads to build systems which are hard to understand and
> which are highly sensitive to particular tool configurations.

This is painfully true, but the situation can be alleviated by
not requiring that the online help contents be regenerated from
source every time.  The reference pages won't change very often.

> 
> So, I'm -1 on generating the help command text from the book (if the
> book authors want to generate refentries from the help documentation,
> they can, but I think it would reduce the quality of the book).  It's
> more work to maintain duplicate documentation, but it yields better
> results, and many more people are going to read our documentation than
> write it.

If man pages are not part of the final deliverable, it is very
likely that errors in the online help will be noticed by the
subversion developers, and errors in the reference pages will be
more likely to be overlooked, because the typical developer will
type "svn help <foo>" much more often than opening up a web
browser to peruse chapter 8.

Making the online help a function of the reference pages should
improve the overall quality.

--
John R. Daily
<email><mailbox>john</mailbox><domain>geekhavoc.com</domain></email>


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: Single source documentation

[Greg Hudson <gh...@MIT.EDU>]

On Wed, 2003-11-12 at 00:01, John R. Daily wrote:
> Earlier this year, the problem of documentation duplication was
> discussed on this list, but apparently nothing ever came of it.
> 
> This evening, I've been experimenting with a process to generate
> the help command text from the refentries in the book, and I have
> an alpha-quality solution.

My experience is that consolidation of documentation often leads to
inferior documentation in many of the places you look for it, because
there are different standards of brevity, precision, and target audience
in different areas of documentation.  It also leads to build systems
which are hard to understand and which are highly sensitive to
particular tool configurations.

So, I'm -1 on generating the help command text from the book (if the
book authors want to generate refentries from the help documentation,
they can, but I think it would reduce the quality of the book).  It's
more work to maintain duplicate documentation, but it yields better
results, and many more people are going to read our documentation than
write it.


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org