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

[Jeffrey Fearn]

Robert P. J. Day wrote:
>   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.

Publican is not a Fedora project and some of the functionality is not 
available in Fedora due to packaging issues. In this case if you don't 
have xslthl installed, which is not packaged for Fedora, then you won't 
see highlighting.

The beta version uses a perl library for this, which is also not in 
Fedora, but it should be easier to get that in to Fedora.

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

It would require a small amount of tweaking to support NG, but it will 
require a massive amount of QA on the changes it introduces.

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

The Red Hat and JBoss brands never made it past Fedora packaging, but 
they are available to RHEL users. publican-genome is a community brand 
and not maintained by the publican team. I'm really happy 
publican-genome got created as it is a shining example of exactly why we 
went with this approach to branding.


Chapter 3 needs a complete rewrite since the beta completely changes the 
interaction of the user.

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

Yup, Publican is not a Fedora project and the instructions cover things 
available on different platforms. We probably need to make that clearer.

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

Cheers, Jeff.

-- 
Jeff Fearn <jfearn at redhat.com>
Software Engineer
Engineering Operations
Red Hat, Inc
Freedom ... courage ... Commitment ... ACCOUNTABILITY
http://file.bne.redhat.com/~jfearn/