You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@click.apache.org by "Gilberto C. Andrade" <gi...@gmail.com> on 2009/01/19 18:38:22 UTC
docbook - modular
Very good!
After some reading I've found that this tag <imagedata
fileref="images/click-logo.png" /> should be <imagedata
fileref="../../images/click-logo.png" />, to render images
correctly.(Off course, when viewing on xxeditor)
One more suggestion, take some oss projects and you will see a docbook
modular (http://www.sagehill.net/docbookxsl/ModularDoc.html) in
particularly all of them. Maybe a way to control the changes and not
everyone changing a big file.
I did the division (click-book.tar.gz) as an excise.
Gilberto
Re: docbook - modular
Posted by Bob Schellink <sa...@gmail.com>.
Gilberto C. Andrade wrote:
> After some work, I didn't resist and use the herold utility:
> herold -i controls.html -o chapter-controls.xml -s UTF-8 -r book
>
> What did I find?
> -the root tag is book: this isn't an problem
> -we are using old doctype specification, this one is the actual:
> [code]
> <?xml version='1.0' encoding='UTF-8'?>
> <!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
> 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd'>
> [/code]
As long as we can still generate the output thats great.
> -I need revise chapter, section and link, just to conform with
> introductions.xml ids pattern (you defined)
We can change the id pattern, as long as its unique and easy to
bookmark. Not sure what ids herold generates.
> -the images link references images/image01.png while introductions.xml
> uses images/introduction/image01.png: I don't know which to follow!
> And these images aren't images folder.
I used the convention that each chapter will have its own images
folder. That way its easier to find images when we have to update
screenshots.
> So, this tool very good and I will use it to help us on this task (
> html tags to docbook xml tags) initially.
Sounds good. Don't worry if the conversion isn't 100%. This is a
one-time task and I'll double check that the output is generated
correctly.
kind regards
bob
Re: docbook - modular
Posted by "Gilberto C. Andrade" <gi...@gmail.com>.
2009/1/21 Gilberto C. Andrade <gi...@gmail.com>:
> 2009/1/21 Bob Schellink <sa...@gmail.com>:
>> On Wed, Jan 21, 2009 at 2:28 PM, Gilberto C. Andrade
>> <gi...@gmail.com> wrote:
>>>
>>> Bob, can I use this reference
>>> http://www.michael-a-fuchs.de/projects/dbdoclet/en/transformation.html,
>>> as HTML -> DocBook XML transformation?
>>>
>>> I'm not using that project, I was looking for a reference on html tags
>>> to docbook xml tags.
>>
>>
>> Sure that looks fine. You should also look at the tags used in the
>> chapter-introduction.xml as that probably covers most
>> markup that is needed. The one tricky area I found with the conversion
>> is how to represent syntax highlighting e.g:
>>
>> <span style="color:red">hello-world.htm</span>
>>
>> Since docbook is only concerned with data, how do we highlight
>> hello-world.htm? Or Velocity directives?
>>
> Right, my indecision was with:
> <ulink>
> <xref>
> <anchor>
> <link>
>
> Controls.hml has an ordered list with inline links, so that was my
> problem, rs rs!
>
>> My workaround was to dedicate certain docbook tags for these
>> scenarios. For example I used <symbol> for Velocity
>> directives and <varname> for Velocity variables.
>>
> Good to know.
>
>> kind regards
>>
> Thanks,
>
> Gilberto
>
After some work, I didn't resist and use the herold utility:
herold -i controls.html -o chapter-controls.xml -s UTF-8 -r book
What did I find?
-the root tag is book: this isn't an problem
-we are using old doctype specification, this one is the actual:
[code]
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd'>
[/code]
-I need revise chapter, section and link, just to conform with
introductions.xml ids pattern (you defined)
-the images link references images/image01.png while introductions.xml
uses images/introduction/image01.png: I don't know which to follow!
And these images aren't images folder.
So, this tool very good and I will use it to help us on this task (
html tags to docbook xml tags) initially.
regards,
Gilberto
Re: docbook - modular
Posted by "Gilberto C. Andrade" <gi...@gmail.com>.
2009/1/21 Bob Schellink <sa...@gmail.com>:
> On Wed, Jan 21, 2009 at 2:28 PM, Gilberto C. Andrade
> <gi...@gmail.com> wrote:
>>
>> Bob, can I use this reference
>> http://www.michael-a-fuchs.de/projects/dbdoclet/en/transformation.html,
>> as HTML -> DocBook XML transformation?
>>
>> I'm not using that project, I was looking for a reference on html tags
>> to docbook xml tags.
>
>
> Sure that looks fine. You should also look at the tags used in the
> chapter-introduction.xml as that probably covers most
> markup that is needed. The one tricky area I found with the conversion
> is how to represent syntax highlighting e.g:
>
> <span style="color:red">hello-world.htm</span>
>
> Since docbook is only concerned with data, how do we highlight
> hello-world.htm? Or Velocity directives?
>
Right, my indecision was with:
<ulink>
<xref>
<anchor>
<link>
Controls.hml has an ordered list with inline links, so that was my
problem, rs rs!
> My workaround was to dedicate certain docbook tags for these
> scenarios. For example I used <symbol> for Velocity
> directives and <varname> for Velocity variables.
>
Good to know.
> kind regards
>
Thanks,
Gilberto
Re: docbook - modular
Posted by Bob Schellink <sa...@gmail.com>.
On Wed, Jan 21, 2009 at 2:28 PM, Gilberto C. Andrade
<gi...@gmail.com> wrote:
>
> Bob, can I use this reference
> http://www.michael-a-fuchs.de/projects/dbdoclet/en/transformation.html,
> as HTML -> DocBook XML transformation?
>
> I'm not using that project, I was looking for a reference on html tags
> to docbook xml tags.
Sure that looks fine. You should also look at the tags used in the
chapter-introduction.xml as that probably covers most
markup that is needed. The one tricky area I found with the conversion
is how to represent syntax highlighting e.g:
<span style="color:red">hello-world.htm</span>
Since docbook is only concerned with data, how do we highlight
hello-world.htm? Or Velocity directives?
My workaround was to dedicate certain docbook tags for these
scenarios. For example I used <symbol> for Velocity
directives and <varname> for Velocity variables.
kind regards
bob
Re: docbook - modular
Posted by "Gilberto C. Andrade" <gi...@gmail.com>.
2009/1/20 Gilberto C. Andrade <gi...@gmail.com>:
> 2009/1/20 Bob Schellink <sa...@gmail.com>:
>> Gilberto C. Andrade wrote:
>>
>>> So, I it is a good argument!
>>> Maybe this article(http://www.vogella.de/articles/DocBook/ar01s04.html)
>>> could help!
>>>
>>> I'm just learning and I don't have experience to choose either one.
>>> But I will try do the best on whatever you choose.
>>>
>>
>>
>> Yeah my experience with Docbook is also limited, however since entity
>> references works with DBF I think we should roll with that until there is a
>> use case where we need XInclude. From what I can see entity references
>> should cater for our needs, which is to break the docs into different
>> chapters and merge them again at build time.
>>
>> I've checked in the modular book to trunk.
>
> Ok! I'm working on chapter-controls.xml right now.
>
> Gilberto
>
>>
>> Btw Hibernate also use entity references for their docs:
>> http://fisheye.jboss.com/browse/Hibernate/core/trunk/documentation/manual/es-ES/src/main/docbook/master.xml?r=11563
>>
>> kind regards
>>
>> bob
>>
>
Bob, can I use this reference
http://www.michael-a-fuchs.de/projects/dbdoclet/en/transformation.html,
as HTML -> DocBook XML transformation?
I'm not using that project, I was looking for a reference on html tags
to docbook xml tags.
Gilberto
Re: docbook - modular
Posted by "Gilberto C. Andrade" <gi...@gmail.com>.
2009/1/20 Bob Schellink <sa...@gmail.com>:
> Gilberto C. Andrade wrote:
>
>> So, I it is a good argument!
>> Maybe this article(http://www.vogella.de/articles/DocBook/ar01s04.html)
>> could help!
>>
>> I'm just learning and I don't have experience to choose either one.
>> But I will try do the best on whatever you choose.
>>
>
>
> Yeah my experience with Docbook is also limited, however since entity
> references works with DBF I think we should roll with that until there is a
> use case where we need XInclude. From what I can see entity references
> should cater for our needs, which is to break the docs into different
> chapters and merge them again at build time.
>
> I've checked in the modular book to trunk.
Ok! I'm working on chapter-controls.xml right now.
Gilberto
>
> Btw Hibernate also use entity references for their docs:
> http://fisheye.jboss.com/browse/Hibernate/core/trunk/documentation/manual/es-ES/src/main/docbook/master.xml?r=11563
>
> kind regards
>
> bob
>
Re: docbook - modular
Posted by Bob Schellink <sa...@gmail.com>.
Gilberto C. Andrade wrote:
> So, I it is a good argument!
> Maybe this article(http://www.vogella.de/articles/DocBook/ar01s04.html)
> could help!
>
> I'm just learning and I don't have experience to choose either one.
> But I will try do the best on whatever you choose.
>
Yeah my experience with Docbook is also limited, however since entity
references works with DBF I think we should roll with that until there
is a use case where we need XInclude. From what I can see entity
references should cater for our needs, which is to break the docs into
different chapters and merge them again at build time.
I've checked in the modular book to trunk.
Btw Hibernate also use entity references for their docs:
http://fisheye.jboss.com/browse/Hibernate/core/trunk/documentation/manual/es-ES/src/main/docbook/master.xml?r=11563
kind regards
bob
Re: docbook - modular
Posted by "Gilberto C. Andrade" <gi...@gmail.com>.
2009/1/19 Bob Schellink <sa...@gmail.com>:
> Gilberto C. Andrade wrote:
>>
>> After some reading I've found that this tag <imagedata
>> fileref="images/click-logo.png" /> should be <imagedata
>> fileref="../../images/click-logo.png" />, to render images
>> correctly.(Off course, when viewing on xxeditor)
>
>
> Nods, however DBF seems to look for images under 'images/'. If the directory
> is moved it can't find the images.
>
> A quickfix would be to either:
>
> # Copy the images folder to the docbook folder for the editor to pickup the
> images.
> # Created a symbolic link from the docbook folder to the images folder
>
OK.
>> One more suggestion, take some oss projects and you will see a docbook
>> modular (http://www.sagehill.net/docbookxsl/ModularDoc.html) in
>> particularly all of them. Maybe a way to control the changes and not
>> everyone changing a big file.
>
>
> Agreed modular sounds good. However DBF fails when generating the output.
I think dbf lacks this feature: https://issues.apache.org/jira/browse/DBF-10.
>
> However an alternative solution (which works in DBF) is to use entity
> references.
>From the link above:
"The XInclude standard permits you to select part of a file for
inclusion instead of the whole file. That is something that system
entities were never able to do. In a modular source setup, that means
you do not have to break out into a separate file every single piece
of text that you want to include somewhere. You can organize your
modules into logical units for writing and editing, and the select
from within a file if you need just a piece of a module.
"
So, I it is a good argument!
Maybe this article(http://www.vogella.de/articles/DocBook/ar01s04.html)
could help!
> click-book.xml:
>
> <?xml version="1.0" encoding="UTF-8"?>
> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
> "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
>
> <!ENTITY chapter-introduction SYSTEM "chapter-introduction.xml" >
> <!ENTITY chapter-controls SYSTEM "chapter-controls.xml" >
> ]>
>
> <book lang="en">
>
> ...
>
> <toc></toc>
>
> &chapter-introduction;
> &chapter-controls;
>
> </book>
>
> Let me know what you think.
I'm just learning and I don't have experience to choose either one.
But I will try do the best on whatever you choose.
Regards,
Gilberto
Re: docbook - modular
Posted by Bob Schellink <sa...@gmail.com>.
Gilberto C. Andrade wrote:
>
> After some reading I've found that this tag <imagedata
> fileref="images/click-logo.png" /> should be <imagedata
> fileref="../../images/click-logo.png" />, to render images
> correctly.(Off course, when viewing on xxeditor)
Nods, however DBF seems to look for images under 'images/'. If the
directory is moved it can't find the images.
A quickfix would be to either:
# Copy the images folder to the docbook folder for the editor to
pickup the images.
# Created a symbolic link from the docbook folder to the images folder
> One more suggestion, take some oss projects and you will see a docbook
> modular (http://www.sagehill.net/docbookxsl/ModularDoc.html) in
> particularly all of them. Maybe a way to control the changes and not
> everyone changing a big file.
Agreed modular sounds good. However DBF fails when generating the output.
However an alternative solution (which works in DBF) is to use entity
references.
click-book.xml:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY chapter-introduction SYSTEM "chapter-introduction.xml" >
<!ENTITY chapter-controls SYSTEM "chapter-controls.xml" >
]>
<book lang="en">
...
<toc></toc>
&chapter-introduction;
&chapter-controls;
</book>
Let me know what you think.
regards
bob