vcs.maemo.org Git - monky/blob - doc/README.docs

   1 DA DOCS. YO.
   2 ============
   3 The main file that contains the bulk of our documentation is docs.xml .
   4 We use the DocBook format, which is a really kickass xml-based way of
   5 writing documentation, heavily oriented towards programming and computer
   6 stuff. There are tags like <command> and <option> that marks up your
   7 content without actually having to mark it up, which is why something
   8 that's of the <command> shows up in some cool style regardless of
   9 whether it's in a man page or a web page. DocBook has been around for
  10 10 years, and there's TONS of resources online about the different
  11 tags and the stuff that can be done.
  12
  13 FILE ORGANIZATION
  14 =================
  15 For the sake of making things readable and organized,
  16 docs.xml "includes" three other files, as of 8/18/05.
  17 These are config_settings.xml, command_options.xml, and variables.xml .
  18 Their names are pretty self-explanatory, and what the "include" essentially
  19 does is stick their contents into docs.xml at the appropriate locations
  20 when it's time to produce a man page or html file. So if you wanted to
  21 add a variable or explain a command line option better, you'd look in
  22 variables.xml and command_options.xml. If you wanted to change the authors
  23 or something, look in docs.xml
  24
  25 BUILDING DA DOCS
  26 ================
  27 (NOTE that the docs are now built automatically via doc/Makefile.am, but it requires that you have docbook2x and xsltproc installed)
  28
  29 making the html is easy. xsltproc should more than likely already be on your system:
  30
  31 xsltproc http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl docs.xml > docs.html
  32 ==============================================================================================================
  33 making the man page is pretty easy, it uses a program called docbook2x, which you might or might not have.
  34
  35 docbook2x-man docs.xml (produces a conky.1 file)
  36 gzip conky.1
  37
  38 conky.1.gz can be viewed in man-form by doing "man -l conky.1.gz"
  39 ==============================================================================================================
  40 making the README (text-only) file is just some simple unix:
  41 man -l conky.1.gz | col -b > README