Re: library.gnome.org status

[Goran Rakic <grakic devbase net>]

У пон, 16. 04 2007. у 14:03 +0200, Frederic Peters пише:
> Hi Goran, (and gnome-web-list@)
> 
> You are in the same timezone as me, it will make things easier :)

Just to warn you, I will be semi-offline from tomorrow until Saturday. I
will have regular net access again after Saturday.


> > - XSLT styles (locators/gtkdoc/gtkdoc.xslt and locators/gdu/gdu.xslt)
> > are not producing markup acording to mockups. Main problem is that there
> > is no navigation sidebar. I also don't know how to include list of
> > languages avaibile as some languages can fail to build (maybe script can
> > try to build all languages first and then reprocess them to include
> > language selector, but that is far from optimal solution)
> 
> As I said in my blog post, my XSLT skills are rusty; also from
> previous experience I don't think it is wise to do everything using
> XSLT.  See next paragraph...

When I started my SoC project, doing everything in XSLT was one of
requirements. Indeed, it is the easiest way as we can reuse same XSLT
from gnome-doc-utils and gtk-doc. But we need to write this patch once,
to include web specific options. I guess we must then beg Shaun to do
the work. :)

Another thing is that I would really like to keep things static, and
annotations can be plugged in via javascript (and them can be dynamic,
as they need to be). I don't see any advantage of having static content
served dynamically. 

And about your idea of using output from xsltproc as input in another
processing, I think that would be too expensive, witout any reason
except list of languages. Everything else can be done in XSLT, just I
don't know how to do it. :)

List of languages is a problem as when, for example, language number
four fails to build we need to process languages 1-3 again (to remove
language four from the list). But instead doing that, we can just remove
output of lang 4th and Apache will serve English as a fallback (and we
are always building English first, and other langs only if English is
built correctly).

What do you think, can we do that or do you think we should process
languages 1-3 to include new list of languages (without language 4 in
the list) or we should apply another transformation (from Python or
another XSLT) to include list of languages on every page after building
is done? Remember then second processing will be expensive as we need to
process every chunk, not just one single document.


> > - There are no index files for browsing documentation by module or GNOME
> > release, and removing old content on upgrade is totaly broken. There are
> > small XML chunks (index.LANG.xml) in output that include informations
> > like localized document title and abstract. My plan was to parse them
> > after building is done and regenerate index pages. Index pages should be
> > localized, and generated for each language avaibile.
> 
> I agree on the goal, it would also be possible to parse omf files to
> get that information.  I would prefer to to this step, "decorating"
> the raw xhtml files, with straight Python (+ a template language, I
> have not been following that closely, genshi or kid come to mind).
> In a second phase this generation could be moved to a web application
> to support things like annotations...

Parsing of omf files is already implemented (there is a category and
others properties, like timestamp of last update in each docitem object
instance - see inline documentation in docobj.py), as well as creation
of XML files with localized title/abstract info. Note that you can't get
title/abstract that before XSLT is applied (as localizations are merged
into docbook file from PO file by xml2po, then XSLT creates additional
chunk with that info).

Then, to create index files, you just need to parse index.LANG.xml files
in output (like http://library.gnome.org/eog/2.16/index.en.xml) and
reuse other infos from each docitem object.


>/module/version/ -> generate list of languages + table of contents
> /module/         -> generate list of versions
> /                -> generate list of modules (and separate help from
>                     API reference)

Your suggestions on URLs are fine for a start, I had the same idea as
you do, but then I realized that the problem is more complex than that.
You have GNOME releases, user and dev documentations, categories etc...

We must separate location on disk from link location. For location on
disk we can use scheme you have suggested with DOCITEM instead MODULE as
one module can have more then one document item and some documents can
be outside any module, located somewhere on the web. 

The problem is that API references usually share same DOCITEM with user
docs, so I decided to group them under api directory (see
http://library.gnome.org/api/). I'm not sure that it is the best
solution. Maybe we can put all developers docs at
http://developer.gnome.org and keep only users and admins docs at
http://library.gnome.org to avoid name collisions? What you and others
think about that?

Once we have location scheme, we can work on URL scheme for index files.

</> can contain introduction, selection of newest documents (only from
latest stable GNOME or not? What about docs not related to any specific
GNOME release, like Shaun's Platform overview or Miguel's Guide for
ISVs) and links to list of all modules and list of past GNOME releases.

</user>, </admin> and </dev> will be the same, presenting only
documentation for users, administrators and developers. Under that we
can present categories to have </user/core_desktop>, </user/applets>
etc, each acting as a filter, and </user/all> which can list all
documents available for users in latest stable GNOME release.

</gnome> can correspond to a list of GNOME releases, including unstable
release and </gnome/unstable>, </gnome/2.16>, etc. can be the same as
</>, but for unstable and 2.16 GNOME releases and not for latest stable
one. </gnome/2.16/user> and others can follow the same pattern.

Next, </documents> can have list of all documents, included or not in
some GNOME release, and </ekiga>, </gedit> can list all versions of
ekiga and gedit user manual (with indicators wich one is included in
some GNOME release).

Finally, </ekiga/2.18> will display user manual for ekiga 2.18, and as
it's the same as storage location there is no need for url rewrite.

If developer documents is included into library.gnome.org, </api> can
list all gtk-doc DOCITEMS, included or not in some GNOME release, and
</api/gobject> (and not </gobject>!!!) can be a list of gobject
versions. Finally, </api/gobject/2.10> will display API documentation
for gobject 2.10.

This is how I planned to do it, but never did. :) Are you interested to
implement this functionality? Do you think there is a better way to
organize things? Are infos inside docitem object enough and should map
of localized title/abstract tuples be part of docitem object as well or
every document should provide index.LANG.xml file?



> You would monitor http://ftp.gnome.org/pub/GNOME/teams/releng/ for new
> versions, then download (example)
>   http://ftp.gnome.org/pub/GNOME/teams/releng/2.18.1/gnome-2.18.1.modules
> and build it in whatever/build-2.18.1/.
> ...
> I would suggest using jhbuild for everything :)
> 

There is no way how you can build API documentation from Subversion
checkout, without having full dependencies installed on server and
running configure script and GNU make.

And you can have filesystem access to tarballs (it's faster to do stat
call then to do svn update when nothing is updated), call content update
script from script for uploading tarball to FTP server etc.

Also, documentation for modules not included in specific GNOME release,
but present on GNOME SVN server should be available through
library.gnome.org so you can't use jhbuild even for unstable release.


> fpeters jabber org is my jabber id; we can also arrange a meeting on
> IRC if other people are interested.

Maybe we can have meeting on IRC (#docs on irc.gimp.org) at Sunday,
April 22, starting at 18:00UTC? If you agree, be free to advertise it on
http://live.gnome.org/DocumentationProject/DocTeamMeetings and p.g.o.


--
Goran