Make a better printable documentation

can we talk french?

I prefer to stay in english, for non-french readers ;-)

bug with upload file $$^$è§tè : je recommence tout !!

You can see the last manual (20080603) from on this page http://www.ensta.fr/~diam/pub/jelix_xml_doc

I see the following warning/errors rais wile compiling but the doc is readable

bug in generated docbook

Is it a xml generate from wiki bug ?

xsltproc --xinclude -o
/var/folders/8H/8HGY1HSlHF4lGBZJE27XkE++3TE/-Tmp-/tmpmLTjou/listings.xml
--param current.dir
'/Volumes/big/home/uma/diam/live/public_html/pub/jelix_xml_doc'
/.../xml/dblatex/dblatex-0.28/share/dblatex/xsl/common/mklistings.xsl
/.../jelix_xml_doc/manuel-jelix-1.0-draft-20080603.xml

/.../jelix_xml_doc/manuel-jelix-1.0-draft-20080603.xml:11143:
element section: validity error : ID references-tplplugins-fonctions already
defined 
     <section id="references-tplplugins-fonctions"><title>Médias</title>
                                                  ^

xsltproc --xinclude -o manuel-jelix-1.0-draft-20080603.rtex 
        --catalogs --param current.dir '/.../jelix_xml_doc'
        --param listings.xml
'/var/folders/8H/8HGY1HSlHF4lGBZJE27XkE++3TE/-Tmp-/tmpmLTjou/listings.xml'
custom.xsl
/.../jelix_xml_doc/manuel-jelix-1.0-draft-20080603.xml

/.../jelix_xml_doc/manuel-jelix-1.0-draft-20080603.xml:11143:
element section: validity error : ID references-tplplugins-fonctions already
defined 
     <section id="references-tplplugins-fonctions"><title>Médias</title>
                                                  ^

missing images

Not sure if this is jelix images or not. I've stollen from the wiki only one image : schema_logic.png. Ih ther are other one, you should provide the full xmldoc with the related image subdirectory (for testing)

XSLT stylesheets DocBook -  LaTeX 2e (0.2.8)
===================================================
Image 'cache/images/2b984eeb072a07d3029821e7031cb8a2.png' not found
Image 'cache/images/c3b5f2f45f303402a2d6c9163b3b5d7f.png' not found
... (about 20~ missing files

validating the process

Can you print some page to see if this pdf can replace yours? (missing figures, ...) If yes, can you start to switch from db2latex to dblatex as primary tool?

Then we can start look for all miss-translated feature from the wiki...

I have some problems with included images in xml file:

• some are specified with relative directory like 'fileref="images/schema_logic.png" '
• other are absolutes as in "/var/www/jelix.org/www/data/media//fr/manuel-1.1/jresponsehtml_step1.png"
• other relative to cache directory "cache/images/2b984eeb072a07d3029821e7031cb8a2.png""

So the prototype of pdf files from [http://www.ensta.fr/~diam/pub/jelix_xml_doc] are not complete and are only usefull to see the page formating (because they only contain one manualy stollen figure)

Now what should one do??

1. choose to keep current jelix.org pdf version (with db2latex) so trash the above forked directory (with dblatex)?
2. try to complete the new pdf doc with all missing figurse. This implies some work to make each xml source directory self contained with all needed figures, but this work is still probably usefull if the next solution is choosed because it allow to make more test on a foreign host.
3. try to build the two pdf versions on the jelix.org server for some times to see if the new doc is easy to maintain. and better enough to switch. Then choose between the two versions and concentrate on the choosen one

The new solution seems to work fine. Good style sheet, good rendering, less pages. And it's very nice to have the contents with links.

My two cents :

• the others internal links doesn't work. It shows the first page.
• not sure of the interest of the "collaborators" and the "revision history" tables.
• is it possible to have syntax highlighting in the code blocks ?

Thanks for this contribution.

the others internal links doesn't work. It shows the first page.

Urls which jump to external links seam to work on both original pdf doc and new one pdf doc
Some urls for internal API references seem to not work neither in original and new one pdf doc.

There is also other problems with path to image with are more critical for a printable documentation. Perhaps some organisation has to be found for images between wiki doc versus xml doc?

not sure of the interest of the "collaborators" and the "revision history" tables

I agree (do know what does Laurent think about that). It was in the original layout of dbatex. I've start a minimal latex style (jelixdoc_fr.sty) which skips these tables and add some french stuffs (chapter names, ...)

is it possible to have syntax highlighting in the code blocks ?

It is done in the wiki (which is very nice). It should be feasable in "LaTeX only" too (there is a listing.sty package that I've never used). But the problem is that this feature need a custom xml docbook build from the wiki format. So it's probably not easy and will be very time consuming...

Images issues won't exist anymore when I will install your new pdf scripts.

But the problem is that this feature need a custom xml docbook build from the wiki format

Which sorts of customization ?

Replying to laurentj:

Images issues won't exist anymore when I will install your new pdf scripts.

great!

But the problem is that this feature need a custom xml docbook build from the wiki format

Which sorts of customization ?

I don't know (I havn't look into it).

Probably the minimal would be to put one information about the language of the listing (generaly php) and this information should be pass from xml to the LaTeX file generated by the tool dblatex. Then a custom environment should be provide by the jelixdoc_fr.sty file. There is many link (maillon) in the tools in the chain; so many sources of problems. (I don't know if (and how) dblatex is able to translate listing informations (parametrers ?) to latex specific environmenent...

As there is some work to do with the documentation. I think the first objective would be to ensure a acceptable standard pdf doc before trying to look at this particular feature. (I've yet to enter into jelix ... ! ;-)

Then I can look at this specific feature with a litle wiki sample (with just a listing or so) to get into the little (but full) docbook file and various generated document to play with.

I've add some global colorisation (common for all listings), and add a left rule to verbatim listing.
Not as good as jelix wiki! but it could be a start?

And I'm even not sure that it's better than nothing because there is some stange colorisation:

• "join" in sql code is seen as a keyword,
• "delete" method in php code is seen as a keyword too...
• ...

You can see it at [http://www.ensta.fr/~diam/pub/jelix_xml_doc]

Hello maurice,

I installed your new files jelixdoc_fr.sty and jelixdoc_params.xsl, I replaced the commands xsltproc + pdflatex by you command line with dblatex, and it seems it works well. You can see the results in the download section :-)

Colorisation is beautiful, thanks for your work !

Do you plan to do some other improvements ? For example, it could be cool to have a beautiful cover. Is it possible to have this improvement ? And if yes, could you show us how to do, by taking a png image which represent the cover and by inserting it at the first page ?

I keep this ticket open, because the cover should be still improved. But it is not a high priority now for Jelix 1.0.5.

Bonjour à tous,

I update the styles (jelixdoc_fr.sty and jelixdoc_params.xsl) on my page at http://www.ensta.fr/~diam/pub/jelix_xml_doc.

Note that this page will be removed when theses modifications are in the official jelix site.

• modif the front page (include one figure : see jelixdoc_fr.sty)
• modif the interline for the table of content (there was too much spaced)
• a param. in jelixdoc_params.xsl could allow to switch from 11pt to 10pt or 12pt)

But missing tables bug is yet present (perhaps more important that the front page figure)

Here are two minimalist table samples for docbook:

1 - the simplest I could build (same width for all colums)

    <informaltable> 
    <tgroup> 
    <tbody> 
    <row>
      <entry role="rowhead">Row heading 1.1</entry>
      <entry>Entry 2.1 popopopop popopopop popopopop</entry>  
      <entry>Entry 3.1</entry>
      <entry>Entry 4.1</entry>
    </row>
    <row>
      <entry role="rowhead">Row heading 1.2</entry>
      <entry>Entry 2.2</entry>  
      <entry>Entry 3.2</entry>
      <entry>Entry 4.2</entry>
    </row>
    </tbody> 
    </tgroup> 
    </informaltable> 

2 - With width specifications

    <informaltable> 
    <tgroup cols="5" colsep="1" rowsep="1" align="left"> 
    <colspec colname="c1"/> 
    <colspec align="left" colwidth="6cm"/> 
    <colspec align="right" colwidth="4cm"/> 
    <colspec align="center"/> 
    <colspec align="center" colwidth="3cm"/> 
    <tbody> 
    <row>
      <entry role="rowhead">Row heading 1.1</entry>
      <entry>Entry 2.1</entry>  
      <entry>Entry 3.1</entry>
      <entry>Entry 4.1</entry>
    </row>
    <row>
      <entry role="rowhead">Row heading 1.2</entry>
      <entry>Entry 2.2</entry>  
      <entry>Entry 3.2</entry>
      <entry>Entry 4.2</entry>
    </row>
    </tbody> 
    </tgroup> 
    </informaltable> 

Maurice

Note that this page will be removed when theses modifications are in the official jelix site.

Please, attach useful files (jelixdoc_fr.sty and jelixdoc_params.xsl) and their updates to the ticket, don't store them elsewhere.

customised xsl and sty files pour dblatex tool