#ubuntu-doc report for 2004-01-19, 20, 21 and 22

[Enrico Zini]

* Asking questions on #ubuntu-doc

 <kbrooks> are all questions welcome? :)
 <sivang> _all_ of them, given they comply with the CoC
 <sivang> and somewhat related to documentation &&|| ubuntu
 <kbrooks> even general questions on ubuntu?
 <sivang> yes
 <sivang> however, be adviced that if a proper answer won't be
          available, you might be offered to write a howto/doc about it :)


* The Gnome User's Manual

Some time ago I said I heard voices of "branding infrastructure" being
worked on for the Gnome User's Manual, that we could use.

Finally I managed to trace the sources of those voices and drag them to
the channel.  This resulted in me asking as many questions as I could to
Shaun (the Yelp and Gnome User's Manual guy): I'm posting the relevant
log, since it's full of useful informations.  If you're in a hurry, skip
over it as there are lots of cool things in this report (but then read
this log tomorrow, ok?)

       * Branding infrastructure intentions

<shaunm> howdy jdub
<shaunm> and the rest of the team
  <jdub> we were wondering what the status of brandable docs in gnome is
         and how we can help
<enrico> people have been talking about working with svn vendor drops to
	 ubuntu-brand the gnome docs, but I remember someone talked
	 about possible better solutions
<shaunm> so what all do you want to do?
	 end of the day, things like the user guide are just going to
	 have to be customized by vendors or replaced wholesale
  <jdub> shaunm: first priority is not forking the documentation ;)
<shaunm> sure
  <jdub> bringing relevant vendor branches to the docs seems far more
         sustainable
<enrico> I imagine change some bit here and there to account for visible
	 changes made by the ubuntu devels (if any); if there are
	 chapters that try to be distribution-independent, making them
	 ubuntu-specific, things like that
         maybe adding a chapter about Ubuntu
<shaunm> but you get things like changes to the panel menu
<shaunm> and those things are so pervasive
  <jdub> yeah
<shaunm> and it would require a lot of conditional rendering
  <jdub> what do you think about entitising menu locations and so on
         or providing macro-like entities built from gnome-menus?
<shaunm> plus maintaining documentation of non-stock stuff in the
         community docs
  <jdub> there are quite a few instances where that would work
  <jdub> pulling info directly from .desktop files, gnome-menus, etc.
<shaunm> which could be a real pain if we had multiple distros doing it,
         each on their own release cycles and such
  <jdub> shaunm: let's concentrate on gnome's release cycle, and
         external branches :)
<enrico> It could already be of help to know what branding facilities
         are already in place for us to use
  <jdub> and centralised changes to the docs that will have positive
         ripple effects :)
<shaunm> the user guide is really the hardest case
<shaunm> although
<shaunm> just about every app doc says something like " To run Five or
         More, select Five or More from the Games submenu of the Main Menu"
<shaunm> and, you know, if the menu is customized, all those docs are wrong
<shaunm> that one's a bad example, because docs ought just to use <menuchoice>
  <jdub> shaunm: could we pull that information from gnome-menus? :)
<enrico> shaunm: ah, ok.  I was about to say: we already entitysed menus
         and we have those things autogenerated for other things
<shaunm> jdub: potentially, but then you're locking the documents into yelp
<shaunm> what happens when you just run gnome-doc-utils on the file to
         build html for the web?
  <jdub> shaunm: could do it at build time; that complicates things though
<shaunm> kde uses a docbook customization, and it annoys me
<shaunm> it complicated things considerably, yes
<shaunm> sigh
<shaunm> how I wish docbook profiling weren't so messed up


       * How to do branding

<enrico> shaunm: so, the best option so far is using vendor drops to
         change the bits that need changing?
<shaunm> at the moment, yes
<shaunm> I'm afraid we just don't have the infastructure in place for
         anything very sophisticated
<enrico> Is there something less sophisticated that can be done, besides
         tweaking entities?
<enrico> (I'm trying to ask meaningful questions hoping that someone
         more knowledgeable than me will join us soon)
<shaunm> well, so
<shaunm> can we see some specific problems?
<shaunm> the real problem with documentation is that everything is
         free-flowing prose
<shaunm> and so if you just do these little replacements here and there,
         you often end up with very awkward prose
<enrico> I see the problem.  Well, I heard of branding efforts being
	 going on and I was wondering, but after this conversation I
	 think we could just go on with vendor drops and then send you
	 some patches sometimes if we improve something you could use
<shaunm> well
<shaunm> see, I don't really work on any of the distros' stuff
<shaunm> and so I don't see the problems as much
<shaunm> to get all this stuff right, we need to get representatives
         from the big gnome distros
<shaunm> and lock them all in a room with me
<enrico> jdub: can you take care of that? :)
<shaunm> and preferably some kde folks as well
<enrico> shaunm: so, noone has been branding the User's Manual so far?
<shaunm> because a lot of this should happen in a cross-desktop way
<shaunm> enrico: no, you guys are the first distro to give a damn
<enrico> Ah, ok, cool.  Then we can pioneer the effort and see what happens

I suggest to have a look at the log on irc.workaround.org as the
discussion continues with interesting and funny bits.


* Sean (froud), Shaun (shaunm) and Alexander (plovs)

Later on, a chat started between shaunm, froud and plovs about lots and
lots of documentation-related things; I'll make a list:

 - How to make a vendor drop of the Gnome User's Manual
   froud sorted out some details with shaunm
 - How to produce a source that is portable accross desktops, avoiding
   lock-in into yelp, and possibly accessing .desktop files to get data
 - Brainstorming of new features:
    - Customizing yelp: customizing glossary.collection, templates,
      turning on and off indexes
    - Expanding/collapsing sections
    - Taking notes in Yelp: users taking notes for themselves, admins
      putting notes for users, sharing notes over the internet
    - Submitting notes to bugzilla through yelp
 - tip: try out "xml startlet"
   <shaunm> it's the grep, sed, and awk of xml

So, if someone wants to help the docteam but likes writing code more
than writing docs, they can join Shaun hacking cool features on Yelp!


* make status

Sean created the automatic status generator that reads data from the
<authorblurb> tags and creates a magic status page with what's happening
in DocBook.  This will be autogenerated with "make status".

All authors please add <authorblurb> tags to the things you're working
on: it's easy quick and cool!  It's the maximum win with the minimum
effort!  For real!  It's not marketing crap!  It's so cool that I don't
know how to describe how cool it is without looking idiot!

Look what plovs says of it:

   <plovs_work> COOL!

(see the DocteamWork wiki page, section "Marking what you do" for a 2
lines description on how it works).

I'll take care of setting up some cronjob to have that automatically
updeated around http://people.ubuntulinux.org/~mako/docteam/ and
whatever the alias is going to be.


* Removed AllPages wiki page

Simon Michael suggested to remove the AllPages wiki page:
 <sm> I think it would be better if not there
 <sm> because the name is misleading (contents link is more complete),
      and it creates confusion about where to parent new stuff
 <sm> I'd like to delete it and let it's children be at the top level

Mako was happy with this, Simon went on and took it away.


* Making cross-references

Nick Loeve (trickie) asked how to make a cross reference to another part
of a docbook: Sean suggested him to use xref, but it doesn't seem to
render in Yelp.

Sean Wheeler (froud) suggested to use "<xref linkend="[someId] "/>",
which should work in Yelp.

It turned out that Nick had version 2.6.4 of Yelp, which has problems.
When this happens, you can either upgrade yelp or generate the html
using make.


* Cross-referencing tip

Sean gave a tip:

 <froud> you can also add id attributes to things like title elements
 <froud> <sect1 id="sect-somename"><title id="title-sect-somename">.....
 <froud> then use <xref linkend="" endterm=""/>
 <froud> where
 <froud> <xref linkend="sect-somename" endterm="title-sect-somename"/>
 <froud> It useful if you want to take the lext link from somewhere else
 <froud> for example from a subtitle

It sounds really cool and worth sharing.  However, I was't online to ask
what's "the lext link": Sean, if you read until here, please add a small
note about it.


Ciao,

Enrico

--
GPG key: 1024D/797EBFAB 2000-12-05 Enrico Zini <enrico at debian.org>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20050123/28044977/attachment.pgp>