#ubuntu-doc report for 2004-01-03

[Alexander Poslavsky]

On Tue, 4 Jan 2005 20:33:17 +0200, Sean Wheller <sean at inwords.co.za> wrote:
> Brilliant as usual Enrico. Thanks.

Yep, same here

> On Tuesday 04 January 2005 05:15, Enrico Zini wrote:
> > #ubuntu-doc report for 2004-01-03
> 
> >    Froud is now starting to focus
> >    on adding content, focusing on the Quick Guide at first.  Plovs warns
> >    that there is another version besides the one in the repo.  I'll have
> >    to find out.

Afaik Corey Burger said he was working on it, but I have been away for
a while so I don't know what's up with that.

> >  - Plovs postponed working on the quickguide because of this, and
> >    focused on the faqguide.

Version #1 is ready, btw

> >  - Menus are going to be defined in a centralised way, and references to
> >    menu items will become really easy to enter in DocBook, in all the
> >    documents we are working on.
> >    Note: this is what I understood about the reasoning behind
> >    "menuchoice", but I could be mistaken.  Froud and Plovs please
> >    correct me if I'm wrong.
> 
> Yes. Menus are used often in manuals. I anticipate they will be used across
> all documents. So the idea is to have their definitions in a single place
> (common/menus/) and define them as entities. This was an author can use
> entity inclusion to bring in the menu actions the user has to do. Since they
> are all defined in a single place it saves physically duplicating the
> menuchoice structure, makes writing faster. Should the menus change is an
> upcoming release then we will not have to search out and replace all
> instances where the menu actions are used. We willjust update the XML
> instance of the menu defined in  common/menus/ and all places where the
> instance was included are automatically updated.

Remember that if you want to add a menu-definition you have to:

1. Write it, and put it in  common/menus/
    eg nvu.xml, which looks like:

<?xml version="1.0" encoding="UTF-8"?>
<menuchoice>
    <guimenu>Applications</guimenu>
    <guimenuitem>Office</guimenuitem>
    <guimenuitem>Nvu</guimenuitem>
</menuchoice>

2. Add it to the svn repo: svn add nvu.xml

3. define it in: libs/global.ent
    you must add a definition eg:

<!ENTITY nvu SYSTEM '../common/menus/nvu.xml'>

4. now you can use it in your document as:

&nvu;

and it will print the contents of common/menus/nvu.xml, which is
pretty neat if you ask me.

Question: How can this benefit translators?

> > * How to validate DocBook document
> >
> > Quick HOWTO by Froud and Plovs:

The HOW-part is from plovs, the TO part from Froud

> >  1. cd to trunk/
> >  2a. xmllint --noout --xinclude --postvalid quickguide/quickguide.xml
> >  2b. xmllint --noout --xinclude --postvalid userguide/usersguide.xml
> >  3c. xmllint --noout --xinclude --postvalid faqguide/faq2.xml
> >
> > If there are validation problems, xmllint will shout; if not it exits
> > silently.  You can test xmllint by inducing an error and seeing the
> > result.
> >
> > You can find xmllint in the libxml2-utils package.
> 
> I added a shell script trunk/validate.sh to make life easier
> 
> SOF
> ~~~~
> #!/bin/sh
> 
> # author: Sean Wheller (froud) sean at inwords.co.za
> # remarks: Use this script to validate your documents.
> # usage: ./validate.sh path/to/xmlinstance.xml
> # example: ./validate userguide/userguide.xml
> 
> xmllint --noout --xinclude --postvalid $1
> 
> ~~~~
> EOF
> 
> 
> > * The "About Ubuntu" page
> >
> > After syncinc with Plovs, Enrico will take care of finding out a later
> > version of the About Ubuntu page and putting it in the repository.
> > In the meantime, I created an AboutUbuntuPage page in the wiki to
> > collect the plans and status of it.

Thanks

> > * make or yelp hang downloading stuff from the Oasis website?
> >
> > Or you get "I/O error : Attempt to load network entity
> > http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"?
> >
> > To fix that, you need to have docbook 4.3 installed (the package is
> > "docbook-xml").

Hmmm, i am up-to-date and still get the error

> > For make, if it doesn't Just Work(TM), try to set the XML_CATALOG_FILES
> > variable in the environment.  For example:
> >   XML_CATALOG_FILES=/usr/share/xml/docbook/schema/dtd/4.3/catalog.xml make
> > ug
> >
> > If yelp cannot find catalogs and they are installed, we may have a bug
> > in Ubuntu.

Hmmmm, I want my Hoary

gr, AP