У пон, 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. > [EMAIL PROTECTED] 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 _______________________________________________ gnome-web-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-web-list
