[publican-list] random observations on svn checkout of users guide

[Robert P. J. Day]

  figured i might as well peruse the users guide from beginning to end
so here's some random observations.

* as i mentioned already, version 0.45 of the UG still has a title of
"0.44"

* section 1.2, "Source-code listings are also set in mono-spaced roman
but add syntax highlighting as follows:"

  - in my browser, i see no example of "syntax highlighting".  am i
    supposed to see something representing an example of
    highlighting there?  it's just straight mono-spaced roman.

* perhaps off-topic but will publican work with the relax ng schema of
docbook 5.0?  it's possible that's mentioned later in the UG and i
just haven't got to it yet.

* Chapter 2 refers to five different brand packages, yet yum sees only
the following at the moment:

$ yum search publican
publican.noarch : Common files and scripts for publishing with DocBook XML
publican-doc.noarch : Documentation for the Publican package
publican-fedora.noarch : Publican documentation template files for fedora
publican-genome.noarch : Common documentation files for genome
publican-ovirt.noarch : Common documentation files for oVirt
$

  where are the packages for gimp, redhat and jboss?  are they in the
works?  and that UG table says nothing about publican-genome (whatever
that is).

* Section 3.1:

  "Run the following command to install the publican package:

     # yum install publican publican-doc

  i would rephrase that as installing the package *and* its associated
  documentation package since, AFAICT, they can be installed
  independently, no?

  and just below that:

    # yum install publican-brand

    Replace brand with redhat, fedora, jboss, ovirt, or gimp.

  we've already noticed that some of those packages don't seem to
  exist, at least for a stock f11 x86_64 install.

* section 3.2 lists the create_book options "--help" and "--man" while
the actual help output lists them as "-help" and "-man".  both work
but perhaps those should be made consistent to avoid confusion.

  also, that list of options in Section 3.2 doesn't mention "--lang".

* still in Section 3.2, the instructions to create a new book fail to
note that, after running that create_book command, you need to "cd
Test_Book" before running ls.  i'm sure readers will notice that right
away but you might as well be explicit to be accurate.

* Figure 3.1 lists an alleged new file "Appendix.xml".  i see no such
file after a book creation.

  time for more coffee.  back in a bit.

rday
--

========================================================================
Robert P. J. Day                               Waterloo, Ontario, CANADA

        Linux Consulting, Training and Annoying Kernel Pedantry.

Web page:                                          http://crashcourse.ca
Linked In:                             http://www.linkedin.com/in/rpjday
Twitter:                                       http://twitter.com/rpjday
========================================================================