implementing TopicBasedHelp

[Richard Johnson]

On Sunday 03 December 2006 07:49, Matthew East wrote:
> I've started a separate branch for some experimentation for implementing
> the topic-based-help specification, since I think that it requires some
> fairly severe changes to the layout of the repository.

Excellent. I was thinking we should setup something seperate as well. I 
noticed the commit logs this morning and knew you were up to something. Good 
deal on this.

> You can grab it here:
> https://docteam.ubuntu.com/repos/branches/topic-based-help/
>
> For now, the branch only includes Ubuntu documents. When we've figured out
> what will ultimately be the structure we adopt, we can merge it back into
> trunk and apply it to the kubuntu/edubuntu/xubuntu directories as
> necessary.
>
> Some notes.
>
> First, inter-linking. I think the best way to do this is simply to use
> normal <link> or <ulink> tags to link to another document. Since this
> isn't easy to do with the current translation structure we use
> (documentname/language/documentname.xml), I think we will have to switch
> to (language/documentname/documentname.xml). This means that relevant
> links should work for all languages without having to do any tweaking or
> substitution or anything.

A note for Kubuntu interlinking. When you link to another document that is in 
help already, <ulink url="help:kubuntu/about_kubuntu">About Kubuntu</ulink>. 
An easy way to see which links to add, go into KHelpCenter and mouse over a 
link in the main window. It will display the link in the bottom bar.

> A number of what used to be chapters of the desktopguide are likely to
> become single documents. I've fixed up a couple of these to show how that
> might work (add-applications and games), and the others are not yet fixed
> up. I've made a note of which ones aren't working in the appropriate
> directory.
>
> Does anyone have any comments on this sort of directory structure? It's a
> bit difficult to predict what problems it might cause, so I'd love some
> feedback.

With the Edubuntu handbook, I broke each chapter into a seperate file. The 
best thing about this is it is easier to task out each chapter. This way here 
you can work on a chapter and not have to worry about someone else needing to 
work on it as well. So breaking down either each topic into a file, or break 
each topic down into subtopic files will work as well. Bringing them all 
together though is the trick, and here is why (please help me if I am wrong). 
Take a look at the Edubuntu Handbook to follow me a little. Look at the 
handbook.xml file to see how I linked each chapter. This makes it look nice 
and neat, but here is the bad thing. When you validate the file, if there are 
errors the message is messy and difficult to debug. Go through and mess up 
one of the files, and then validate the handbook to see what I am getting at. 
When you get a validation error, it will say like 'Line 1388 in handbook.xml 
but it is actually referring to another file and not the handbook.xml file. 
So that is tricky. Of course, if you have a better way of doing this, let me 
know so I can apply it to the handbook as well.

Thanks Matt for rocking this out.

-- 
.:Richard Johnson
.:nixternal at ubuntu.com
.:ubuntu.com .:kubuntu.com .:edubuntu.com .:xubuntu.com
.:http://nixternal.ubuntu-rocks.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20061203/d98bca0e/attachment.pgp>