docs/sitka/sitka_documentation.adoc

   1 = Steps to build AsciiDoc version of Sitka's documentation =
   2
   3 I have included a snapshot of an Asciidoc version of Sitka's documentation in
   4 `docs/one_big_sitka.adoc`.
   5
   6 This is not perfect by any means but should get us at least towards reasonable
   7 markup.
   8
   9 . Install `pandoc` - this tool can convert from one format (such as DocBook) to
  10 another (such as AsciiDoc).
  11
  12 . Clone the Sitka docs repository:
  13 +
  14 [source,sh]
  15 --------------------------------------------------------------------------------
  16 git clone git://git.sitka.bclibraries.ca/sitka/doc/manual.git sitka
  17 --------------------------------------------------------------------------------
  18
  19 . Change into the Sitka docs directory you just created:
  20 +
  21 [source,sh]
  22 --------------------------------------------------------------------------------
  23 cd sitka
  24 --------------------------------------------------------------------------------
  25
  26 . Merge the separate DocBook XML files into one big XML file:
  27 +
  28 [source,sh]
  29 --------------------------------------------------------------------------------
  30 xmllint --xinclude --output one_big_file.xml root.xml
  31 --------------------------------------------------------------------------------
  32
  33 . Convert the one big DocBook XML file into one big AsciiDoc file:
  34 +
  35 [source,sh]
  36 --------------------------------------------------------------------------------
  37 pandoc -f docbook -s one_big_sitka.xml -t asciidoc -o one_big_sitka.adoc
  38 --------------------------------------------------------------------------------
  39
  40 . Run AsciiDoc against it to generate some HTML. There might be some errors
  41 that you need to fix manually, such as lines starting with:
  42 +
  43 [source,sh]
  44 --------------------------------------------------------------------------------
  45 ["2
  46 --------------------------------------------------------------------------------
  47 +
  48 that you need to prefix with a pipe:
  49 +
  50 [source,sh]
  51 --------------------------------------------------------------------------------
  52 |["2
  53 --------------------------------------------------------------------------------
  54
  55 Enjoy!