[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-doc-english
Subject:    [kde-doc-english]What's going on... some help with the recent changes, and the new tools
From:       Lauri Watts <lauri () kde ! org>
Date:       2001-05-07 22:26:15
[Download RAW message or body]

Hi,

I'm still sorting out TODO lists, and collating things, but I thought some 
quick notes about what's happening might help you all feel less neglected.

Firstly, the XML transformation has happened, for those of you not up to date 
in CVS.  All English documentation is now in XML, and most of the i18n docs 
are also in XML now.  

One of the major advantages you will find here is that updating small 
sections of documents is not going to get us yelled at by translators 
anymore.  This means anyone out there with a document that's nearly done, or 
is missing only a couple of chapters, feel free to send it in, and we'll get 
it committed - adding the new chapters later won't cause a massive headache 
for the translators as it did before.  Of course, this doesn't mean we should 
change a line here or there three times a week for the sake of it, but if you 
want to change just a line or two somewhere to clarify something in a 
document, then feel free to do so.

The documents have also had some comments inserted, in the <bookinfo> 
section, and in the credits chapter, as placeholders for the translators to 
add their own credits with the semi-automated translation process.

Eric has normalized the dates, to ISO format (which is YYYY-MM-DD).  I 
know the previous use of british style dates often caused confusion, and 
since Sweden is the only place i know of that uses ISO format as the normal 
day to day date format, this new one should be equally confusing to all 
nationalities except for me (heh, and it wasn't even my idea!)

These three changes make it important that you make very sure you have the 
most recent copy of the docs to work from.  With another release coming up 
fairly quickly, you might like to update all of CVS as well as just updating 
your docs.  Even if you don't, I strongly suggest you take at least the 
following steps:

1: download the most recent copy of libxml2 from http://www.xmlsoft.org/, and 
compile and install it.  I'm currently running 2.3.7, but anything even newer 
than that will be better - you can even try CVS head if you like, it's mostly 
stable.  Instructions for cvs download are on their website.

2: Update in the kdebase module, especially the directory kioslave/help/  
All the new KDE tools are there, including the XML DTD's, and the processing 
tools.  Compile and install that as well (ask me for help if you need it.)

3: The new tools install in $KDEDIR/share/apps/ksgmltools2/ (note the 2!). 
For those of you using DTD aware editors (ok, for those of you with emacs + 
psgml), you need to add the two new catalogs into your tools.  I've had the 
most success with emacs by replacing all the others that I did have with just 
the two new ones, but this is only practical if you don't intend editing any 
other DTD based documents.

The catalogs are $KDEDIR/share/apps/ksgmltools2/customization/catalog and in 
$KDEDIR/share/apps/ksgmltools2/docbook/xml-dtd-4.1.2/docbook.cat 

For those using emacs, the variable to change in your .emacs is 
sgml-catalog-files.  You can reach it from within emacs with the following 
incantation: M-x customize-apropos-options RET sgml-catalog-files RET

There are some small problems using PSGML now, but you can fix most of them 
by sticking to sgml-mode, not xml-mode.  Most of our docs should auto load 
this, if you find one that doesn't, please let me know and I'll fix it.

4: Externally, you can use "checkXML index.docbook" to check syntax in a 
konsole.  You can also use "meinproc index.docbook" to generate HTML pages in 
the current directory.  Finally, you can use help:/yourapp/ to see how the 
pages are generated on the fly.

As for differences in editing XML vs SGML, you will find there are hardly 
any.  All elements must be closed, but most of them were before, so this 
applies to the following only: <anchor> <imagedata> <xref> are now <anchor/> 
<imagedata/> <xref/>.  You may have seen xml tutorials recommending a space 
before that closing /, and if you are in the habit of doing that, it's fine, 
but it's not required.  Otherwise, the docs have been in XML syntax for a 
long time, with all attributes quoted, elements lowercased, and closing tags 
on all elements, so, we should already be in the good habits needed.

Other news the markup.docbook is complete, except for some problems in markup 
for program examples, which won't affect most documents.  I'll post a link to 
that tomorrow, and it'll likely be in the CVS somewhere so you can keep it 
updated with the current KDE documentation guidelines.  Write me and I'll 
send a copy if you can't wait until then!

And finally there will be starting up a new project, in conjunction with the 
Documentation team, and they will be doing proofreading of both the GUI and 
the documentation.  The proofreading team will be using this mailing list for 
discussion, at least to start with, as most of what they have to say will 
either be of interest to the doc writers, or could use the writers input. 
Part of this initiative is to get the docs into the US English they are 
supposed to be written in, which also brings up the idea of reviving the UK 
English i18n team.  Anyone interested in helping out the proofreading 
project, or getting involved in a UK docs project, please write to me and 
I'll direct you to the right people.

I'm also looking for someone to work on the following major applications 
manuals.  These are large applications with either very old documentation, or 
no documentation at all.  You will find a full list of unmaintained documents 
at http://i18n.kde.org/teams/en/current.html, if you'd like to take on one of 
the smaller docs, or take over one which has recently lost it's maintainer.

KSpread (Erwan Loisant is the maintainer, but Kspread is enormous, and he 
could sure use some help)
Killustrator
Kivio
Kate
Noatun
KSirc
The KDE Glossary - this is new, and mostly the job will be adding submissions 
from other people, which is a bit tedious, but someone needs to do it.  If 
you haven't seen it, the glossary is a new tab in the KHelpCenter, and it's 
quite fabulous, thank you Frerich Raabe for his work.
Quanta (which has docs, but they aren't very "KDE'ified" yet, and will take 
some work)

I think that's all for general news, I'll be posting more news as I get 
things organised over the next couple of days.

Regards, 

[prev in list] [next in list] [prev in thread] [next in thread]