doc/README

                      Documentation for Subversion
                      ============================

A rough guide:

  http://svn.red-bean.com/svnbook/
                             Subversion: The Definitive Guide. This is
                             the book that has been published by
                             O'Reilly & Associates. For both newbies and
                             experts alike.  Written in DocBook Lite,
                             and now maintained in a separate repository
                             of its own.
                             
  misc-docs                  Holds additional DocBook Lite material that
                             either isn't yet ready to go into the
                             Definitive Guide, or which may never go
                             into the Guide but instead into companion
                             documents that would be available from the
                             Subversion site.  Think of it as a
                             temporary, but published, holding area.

  HOWTO.DocBook              Instructions on how to build HTML, PDF, 
                             or PostScript from DocBook Lite source.

  programmer/                Documents for Subversion programmers.

  programmer/design/         Subversion's original design document
                             (written in Texinfo).
                             WARNING!  Extremely old!  From June 2000.

  programmer/WritingChangeLogs.txt
                             A longer version of the info in HACKING.

  user/                      Documents for Subversion users.

  user/lj_article.txt        An introductory article from Linux Journal.

  user/svn-ref.tex           LaTeX source for an svn quick-ref sheet.

  user/*.html                Some documentation that should probably be
                             migrated to DocBook Lite and misc-docs/.

  translations/french        A translation of the Subversion handbook
                             (which has been absorbed into the book).
 
If you'd like to document a new feature, try to find a place for it
somewhere in misc-docs.

-------------- NOTES on Texinfo usage -----------------------------

Some of Subversion's documentation is in texinfo format.
The online documentation for texinfo is at:

  http://www.gnu.org/manual/texinfo-4.0/html_chapter/texinfo_toc.html

To build particular things, you'll need one or more of:

  * the 'makeinfo' program from the latest texinfo package in
    ftp://ftp.gnu.org/pub/gnu/texinfo/
  * the 'texi2dvi' or 'texi2html' programs
  * the 'dvipdf' script from Ghostscript (pipes dvi | ps | Ghostscript)


Use these rules for determining how to label something.  These rules
were derived from

http://www.gnu.org/manual/texinfo-4.0/html_chapter/texinfo_toc.html

1) Use <quote>...</quote> for quoting any text in the Subversion book.
   [Do not use the standard Texinfo practice which is `` and ''.
   Do not use a single ' or a single ".]
2) When quoting single characters, such as discussing the output from
   an svn merge or svn update, use @samp{}.
3) Use @samp{} for any commands to run on the command line.  Do not use
   @command{}, this is for the program itself.  So use @samp{ls -l},
   but refer to ls as @command{ls}.  For svn, svnadmin, svnlook
   subcommands, use @samp{}, so to refer to svnlook's youngest
   subcommand, use @samp{youngest}.
4) Use @option{} for command line options to programs that are not
   listed with the program.  So @samp{ls -l}, but refer to -l as
   @option{-l}.
5) Use @uref{} for URLs that anybody on the Internet can access.
   These are converted to real links in HTML pages, while @url{}'s are
   not.  Use @url{} for sample http:// or file:// URLs.  For any
   @uref{} URLs that refer to a site's home page or a directory, place
   a / at the end of the URL.  This saves a redirect and loads the
   page faster.
6) Svn keywords, i.e. svn:ignore, should be in @samp{}.
7) Use @dots{} instead of ``...'' and @enddots{} instead of ``....''.
   Do not use @dots{} or @enddots when showing the output of a command
   and the command really does print the ...'s, such as when ``svn
   commit'' runs.  Do use @dots{} when truncating the example output
   of a command, such as ``svn checkout'', and you don't want to list
   every line of output.  Do not put the ...'s in [] because with
   @dots{} or @enddots{}, the formatted output will use a smaller font
   and the ...'s will be visually distinct already.

-------------
JimB fixed up a lot of our Texinfo problems, here's what he says:
-------------

Anyway, once I can commit things, here's the scoop:

- Info builds cleanly, so I've removed the --no-verify flag from the
  makeinfo command.  Any complains can be taken as real problems.
- The dvi builds without complains about undefined cross references.


As far as I can tell, our tools should work for us exactly as we'd
hope:

- There is no need to list next, prev, and up links in our @node
  lines.  (Certainly a critical requirement.)

- The Emacs commands can rebuild all our menus automatically and
  accurately.

- makeinfo will only complain about real problems.


The only real problem is that makeinfo's error messages are pretty
unhelpful.  It often misidentifies the error, so it's not at all
obvious how to fix a file it doesn't like.  But here are the rules we
have to follow; I found problems in each of these areas.

- @node and sectioning commands (@chapter, @section, ...) should
  always come in pairs --- the @node command on one line, and the
  sectioning command on the very next line.  This goes for the ``top''
  @node as well, which should be followed by a @top command.

- @node names must be globally unique.  This is an unfortunate
  property of info, but it's inherent in the format.  Ben had a lot of
  ``Overview'' nodes.

- @menu commands should be properly formatted.  They should look like
  this:

    @menu
    * Filesystem::
    * Server Library::
    @end menu

  Not this:

    @menu
    * Filesystem
    * Server Library
    @end menu

  If we always use C-c C-u C-a, this should just work.

- @menu commands should always list the correct nodes.

When these rules are broken, the error messages from makeinfo are
pretty unhelpful --- bordering on utterly random.  They complain that
nodes are undefined when they're perfectly clearly correct.

We should always use C-c C-u C-a (`texinfo-all-menus-update') to
reconstruct a file's menus, instead of editing the menus by hand.
That will eliminate the bottom two problems.

You can also give a prefix to C-c C-s, which tells it to list the
@node commands alongside their sectioning commands.  This is helpful
for finding mismatches.

============================================================================
JimB also says:
============================================================================

For defining functions, you should definitely use @deffun or
@deftypefun, not @itemize nor @table.