Documentation for Subversion ============================ Subversion's preferred documentation system is texinfo. 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) A rough guide: book/book Subversion: The Definitive Guide. This is the book that will be published by O'Reilly & Associates. For both newbies and experts alike. Read book/README for instructions on how to build html, PDF, or postscript (the book is marked up in Docbook-lite). book/misc-docs Holds 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 will also be available from the Subversion site. Think of it as a temporary, but published, holding area. programmer/ Documents for Subversion programmers. programmer/design/ Subversion's original design document. (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. 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 book/misc-docs. -------------- NOTES on Texinfo usage ----------------------------- 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 ... 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.