Okay, I'm feeling productive again and have a lot of ideas for the GDP.
Some of them have been brought up earlier but dismissed due to insufficient
resources, others are ideas I've stolen from people that didn't dare to tell
it out loud, the rest is fairly new and due to a huge cafeïne concentration
in my body.
My first observation is that we have an abstract tag in each of our
documents (mandatory) that's only used for the upper right corner. It seems
to me that this abstract can very well be used as a description of the
document for our index page.
What I was thinking about is to write an XML format (to be chained to
GuideXML) that includes each document and automatically uses the abstract as
a description. This format would make it possible to have two documentation
index'es:
- index.xml, desktop.xml and additional index'es that look the same as
they are now (but with the abstract information)
- list.xml which contains links to every single document we have without
additional information
This latter is something cam also requested (one document that lists them
all) and I proposed something along the lines of
<ul>
<li>
Category 1
<ul>
<li><uri link="${DOCUMENT}">${DOCUMENT_TITLE}</uri></li>
...
</ul>
</li>
<li>
Category 2
...
</li>
...
</ul>
Writing such an XML (well, actually DTD+XSL+XML) is fairly simple, *but*
since I'm always trying to get Xavier on my neck with my proposals, I'd like
to go even further and have his TradsXML format that he uses for the translation
summary incorporated. I believe (although I haven't written a POC yet) that
we can have such a translation summary incorporated so that this is
available on the official website.
And, to make things even worse, I'm thinking about extending the book.dtd
definition to have a <version> and <date> entity within the <sections>
entity (mandatory) so that each hb-* file has it's own version/date
information.
I was (but have dropped the idea) thinking about adding an optional
attribute to the "version" tag that had information about the English
revision, so that translated documents could have:
<version english="1.32">2.1</version>
in which the "english" attribute referenced the CVS Revision of the English
document to which the document was translated, but I dropped the idea
because it's confusing and the above proposal (Xavier's TradXML format)
includes the necessary information already.
So, short summary:
- Write an XML to be chained to GuideXML that incorporates Xavier's
TradXML format
- Have index.xml and others automatically generated from the abstract
information
- Have a single document that links to all existing documents
Thoughts? Ideas? I won't do anything about this for at least 5 days so that
everything can be thought of and discussed properly (I know I have the bad
habit of pushing things which is why I force myself upon this 5 days "lag").
Wkr,
Sven Vermeulen
--
Documentation & PR project leader
The Gentoo Project <<< http://www.gentoo.org >>>
Some of them have been brought up earlier but dismissed due to insufficient
resources, others are ideas I've stolen from people that didn't dare to tell
it out loud, the rest is fairly new and due to a huge cafeïne concentration
in my body.
My first observation is that we have an abstract tag in each of our
documents (mandatory) that's only used for the upper right corner. It seems
to me that this abstract can very well be used as a description of the
document for our index page.
What I was thinking about is to write an XML format (to be chained to
GuideXML) that includes each document and automatically uses the abstract as
a description. This format would make it possible to have two documentation
index'es:
- index.xml, desktop.xml and additional index'es that look the same as
they are now (but with the abstract information)
- list.xml which contains links to every single document we have without
additional information
This latter is something cam also requested (one document that lists them
all) and I proposed something along the lines of
<ul>
<li>
Category 1
<ul>
<li><uri link="${DOCUMENT}">${DOCUMENT_TITLE}</uri></li>
...
</ul>
</li>
<li>
Category 2
...
</li>
...
</ul>
Writing such an XML (well, actually DTD+XSL+XML) is fairly simple, *but*
since I'm always trying to get Xavier on my neck with my proposals, I'd like
to go even further and have his TradsXML format that he uses for the translation
summary incorporated. I believe (although I haven't written a POC yet) that
we can have such a translation summary incorporated so that this is
available on the official website.
And, to make things even worse, I'm thinking about extending the book.dtd
definition to have a <version> and <date> entity within the <sections>
entity (mandatory) so that each hb-* file has it's own version/date
information.
I was (but have dropped the idea) thinking about adding an optional
attribute to the "version" tag that had information about the English
revision, so that translated documents could have:
<version english="1.32">2.1</version>
in which the "english" attribute referenced the CVS Revision of the English
document to which the document was translated, but I dropped the idea
because it's confusing and the above proposal (Xavier's TradXML format)
includes the necessary information already.
So, short summary:
- Write an XML to be chained to GuideXML that incorporates Xavier's
TradXML format
- Have index.xml and others automatically generated from the abstract
information
- Have a single document that links to all existing documents
Thoughts? Ideas? I won't do anything about this for at least 5 days so that
everything can be thought of and discussed properly (I know I have the bad
habit of pushing things which is why I force myself upon this 5 days "lag").
Wkr,
Sven Vermeulen
--
Documentation & PR project leader
The Gentoo Project <<< http://www.gentoo.org >>>