| 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 <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. |