developer.jelix.org is not used any more and exists only for history. Post new tickets on the Github account.
developer.jelix.org n'est plus utilisée, et existe uniquement pour son historique. Postez les nouveaux tickets sur le compte github.

Opened 12 years ago

Closed 12 years ago

#606 closed enhancement (fixed)

Make a better printable documentation

Reported by: maurice Owned by:
Priority: low Milestone: Jelix 1.0.6
Component: web site: documentation - do not use - Version:
Severity: minor Keywords:
Cc: Blocked By:
Blocking: Documentation needed: no
Hosting Provider: Php version:

Description

This ticket start from the following forum (french) discussion http://jelix.org/forums/read.php?10,2680 about printable documentation for jelix.

Current jelix documentation is written online in some dokuwiki format, and Laurent build a system to convert the wiki doc to a pdf book.

The current solution is to build a docbook (xml) version of the book formed from a manualy selected set of wiki pages. The (these) xml file(s) is then converted to pdf using (python) dblatex utility. Several problems can occur or enhancement can be requiered:

  • wiki syntaxe can be enhanced to provide some more semantic needed by the docbook output,
  • xml docbook can contain bug from the translation from wiki (e.g. tabular?)
  • dblatex style can be improve either by .xsl style or by latex .sty files.

I suggest:

  • to consolidate the documentation workflow (to validate the chosen tools e.g dblatex ): is it easy to install?, ...,
  • to trac all bugs in printable documentation (e.g tabular bugs, missing figures, bad formating,lines two long in listings, ...) => call for contributions?
  • to dispatch the bug between the workflow state (wiki syntaxe, wiki parser, xml docbook generation, xsl style and latex .sty)
  • to start a jelix specific style (xsl and/or latex .sty) for dblatex.

Maurice

P.S. can we talk french?

Attachments (1)

dblatex_styles_for_jelix-20080730_14h39.tgz (3.5 KB) - added by maurice 12 years ago.
customised xsl and sty files pour dblatex tool

Download all attachments as: .zip

Change History (15)

comment:1 Changed 12 years ago by laurentj

  • Version 1.0.4 deleted

can we talk french?

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

comment:2 Changed 12 years ago by maurice

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

comment:3 Changed 12 years ago by maurice

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/mediafr/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

comment:4 Changed 12 years ago by letibetain

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.

comment:5 Changed 12 years ago by maurice

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

comment:6 follow-up: Changed 12 years ago by laurentj

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 ?

comment:7 in reply to: ↑ 6 Changed 12 years ago by maurice

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.

comment:8 Changed 12 years ago by maurice

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

comment:9 Changed 12 years ago by laurentj

  • Milestone set to Jelix 1.0.5
  • Priority changed from normal to highest

comment:10 Changed 12 years ago by laurentj

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 ?

comment:11 Changed 12 years ago by laurentj

  • Milestone changed from Jelix 1.0.5 to Jelix 1.0.6
  • Priority changed from highest to low
  • Severity changed from normal to minor

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.

comment:12 Changed 12 years ago by maurice

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

comment:13 Changed 12 years ago by laurentj

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.

Changed 12 years ago by maurice

customised xsl and sty files pour dblatex tool

comment:14 Changed 12 years ago by laurentj

  • Resolution set to fixed
  • Status changed from new to closed

Your latest improvements have been installed on the web site. I close the ticket. For other improvements, create new tickets.

Thanks Maurice.

Note: See TracTickets for help on using tickets.