| Design documentation for Subversion is here. |
| |
| You'll want to get |
| |
| ftp://ftp.gnu.org/pub/gnu/texinfo/texinfo-4.0.tar.gz |
| |
| and use the up-to-date `makeinfo' found therein. |
| |
| ============================================================================ |
| JimB fixed up a lot of our Texinfo problems, here's what he says: |
| ============================================================================ |
| |
| I think I've got things straightened out now. Unfortunately, I don't |
| seem to have permission to check anything into the repository. We are |
| working on the Tigris repository again, right? |
| |
| savonarola:doc$ cvs commit |
| cvs commit: Examining . |
| Waiting for Emacs...Done |
| cvs server: User 'jimb' cannot access . |
| cvs server: User 'jimb' cannot access . |
| cvs server: User 'jimb' cannot access . |
| |
| |
| 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. |