Docbook files editing guidelines

[Frank Schoolmeesters]

Hi guys,

If you like to edit the docbook documentation files,
please read the next guidelines first.

btw.
Richard i'm still working at the doc's ;) , when i'm ready if will notify you.


1)
If you like to edit the docbook files, please contact me first,
maybe somebody else might working already at the doc files.
There are two reasons for this:
- i might *uncommit* your work by accident,
since usually i only commit *big changes* and not small issues
- merging 2 docbook files is sometimes *a hell of a job* and takes
a lot of time (I prefer not to do that :-)
So i personally prefer that only one person is
working at the docs, and not multiple persons.
ofcource: if you take notes of things that needs to be edited
allows that more than one person works at the same time.


2)
docbook file are difficult to read with all the tags,
so for proofreading produce an HTML version,
and if you find some issues, open the the coreesponding
docbook file and fix it.
(don't fix the HTML files, it's *useless*)

$ cp krusader_kde3/doc/en/*.docbook ~/foodir
$ cp krusader_kde3/pics/en/*.png ~/foodir
~/foodir>$ meinproc index.docbook

The latter command will produce the HTML files, maybe the stylesheets
are not ok, but for a proofread it's maybe better to have no
stylesheets at all, so that you can focus on the text :)

3)
Don't skrew up the human readability of the docbook files with your editor.
Explained more in detail at below.

Please test first your favorite editor, often they have
automatic formatting of text enabled, if this is active
you will *screw up the formatting of the text* and it
will kill the human readabiltiy of the docbook file.
To skrew up the human readability you need just click the save button :-)
To *fix the human readability* you will need many hours ... :(

So i consider this important since i have skrewed up
the human readability too many times in the past :-) ,
and Richard and Terry encountered the same problem too.

It's very easy to test your editor.
Open a docbook file with your editor (e.g. Krusader editor, kwrite, ...),
installation.docbook is a good candidate, since this file is quite *complex*
and "Save as" installation_bis.docbook

- the fileszize of both docbook files must stay the same
- $ diff installation.docbook installation_bis.docbook
may not report any difference
If the above 2 points are not ok, it means that some automatic formatting is
active and that means that your editor will *skrew up the human readablily*.

For info:
These are the settings for the Krusader editor:
a)
Settings->Configure Editor->Editing
disable "Static Word Wrap"

b)
Settings->Configure Editor->Indendation
*disable automatic indendation
*disable indendation with spaces

c)
Settings->Configure Editor->View Defaults
disable dynamic wordwrap for readability (recommended)


What does Franks means with human readable ? :-)
Well if the *manual indendation* is skrewed up.

Human readable
-------------------
<screenshot>
<screeninfo>&krusader; Logo</screeninfo>
<mediaobject>
<imageobject> bla bla bla </imageobject>
<imageobject> bla bla bla </imageobject>
</mediaobject>
</screenshot>
-------------------

Killed human readbility
-------------------
<screenshot><screeninfo>&krusader; Logo</screeninfo><mediaobject>
<imageobject><imagedata fileref="krusader_title.png"
format="PNG"/></imageobject>
<imageobject><imagedata fileref="krusader_title.png"
format="EPS"/></imageobject>
<textobject><phrase>&krusader;
Logo</phrase></textobject></mediaobject></screenshot>
-------------------

both will compile, but the latter is verry annoying to read by humans.
I dit made a short version of the human readable version,
because the *e-mail max number of characters per line* was skrewing up the
human readablility :-)

btw1.
i have made (again :-) some docbook files more human readable
http://cvs.sourceforge.net/viewcvs.py/krusader/krusader_kde3/doc/en/
"better human readability and some minor fixes (part1)"
index.docbook, introduction.docbook and using-krusader.docbook (partial)

btw2.
this is a draft for the *docbook guidlines* for the Wiki


thanks a lot,

Frank

[W. T. Fudoki Wilkinson]

Hey!  It was that stupid software that screwed up the readability, not Richard and me.....  I'm just using nano from now on  - so nobody can blame me, 'cause I didn't do it!!  ;-)

T.

[Frank Schoolmeesters]

Again a *fresh e-mail* sended out 1 hour ago :-)

I have skrewed it up the formatting many times :-)
even many times without knowing it :-)
Often discovered it when it was *to late to fix it*

If you just *test* your editor like described (filesize and diff) ,
you will not skrew it up.
I have no idea if nano has syntax highlighting like the krusader editor
or kwrite has.

Frank

[W. T. Fudoki Wilkinson]

nano barely has characters! ;-)  no, nano has nothing but a bare edit capability.  actually I am going to experiment with some of the new "XML/Docbook editors - but will only send you the output if it looks good to me, and only on a "test" document.  It's just easier to do it "the old fashioned way" - the way I am used to....

terry

[Richard/g]

El Jue 30 Jun 2005 17:00, Frank Schoolmeesters escribió:
> Again a *fresh e-mail* sended out 1 hour ago :-)
>
> I have skrewed it up the formatting many times :-)
> even many times without knowing it :-)
> Often discovered it when it was *to late to fix it*
>
> If you just *test* your editor like described (filesize and
> diff) , you will not skrew it up.
> I have no idea if nano has syntax highlighting like the
> krusader editor or kwrite has.

OK, just turned off most of my favorites. :-Ç
I'm probably the cause of the misformatting. But now the k-part
works as directed. Using ISO-8859-1 since it seems to cause
less problems. UTF-8 is nice but seems like a standard that is
still needing supporters.

> Frank
>
> On 6/30/05, W. T. Fudoki Wilkinson <fudoki.w...@gmail.com>
wrote:
> > Hey! It was that stupid software that screwed up the
> > readability, not Richard and me..... I'm just using nano
> > from now on - so nobody can blame me, 'cause I didn't do
> > it!! ;-)

I'm too lazy to use nano. :-))

saludos,
Richard.


> > T.
> >

[Frank Schoolmeesters]

On 7/1/05, Richard/g <richar...@gmail.com> wrote:
>
> El Jue 30 Jun 2005 17:00, Frank Schoolmeesters escribió:
> > Again a *fresh e-mail* sended out 1 hour ago :-)
> >
> > I have skrewed it up the formatting many times :-)
> > even many times without knowing it :-)
> > Often discovered it when it was *to late to fix it*
> >
> > If you just *test* your editor like described (filesize and
> > diff) , you will not skrew it up.
> > I have no idea if nano has syntax highlighting like the
> > krusader editor or kwrite has.
>
> OK, just turned off most of my favorites. :-Ç

what do you mean ?

> I'm probably the cause of the misformatting. But now the k-part
> works as directed. Using ISO-8859-1 since it seems to cause
> less problems. UTF-8 is nice but seems like a standard that is
> still needing supporters.
>

> saludos,
> Richard.
>

i think the docbook files are just simple ascii
Special chars are defined like e.g. "&ouml;"
Just take a look at credits.docbook , many names contains special characters.

Frank

[Frank Schoolmeesters]

On 7/1/05, W. T. Fudoki Wilkinson <fudoki.w...@gmail.com> wrote:
> nano barely has characters! ;-) no, nano has nothing but a bare edit
> capability. actually I am going to experiment with some of the new
> "XML/Docbook editors - but will only send you the output if it looks good to
> me, and only on a "test" document. It's just easier to do it "the old
> fashioned way" - the way I am used to....
>
> terry

Since the "XML/Docbook editors" have some even more automated stuff i guess,
i prefer an text editor with xml/docbook highlighting.
e.g. Krusader editor, kwrite, kate.

Frank

[Frank Schoolmeesters]

On 7/1/05, Frank Schoolmeesters <frank.scho...@gmail.com> wrote:
> On 7/1/05, Richard/g <richar...@gmail.com> wrote:
> >
> > El Jue 30 Jun 2005 17:00, Frank Schoolmeesters escribió:
> > > Again a *fresh e-mail* sended out 1 hour ago :-)
> > >
> > > I have skrewed it up the formatting many times :-)
> > > even many times without knowing it :-)
> > > Often discovered it when it was *to late to fix it*
> > >
> > > If you just *test* your editor like described (filesize and
> > > diff) , you will not skrew it up.
> > > I have no idea if nano has syntax highlighting like the
> > > krusader editor or kwrite has.
> >
> > OK, just turned off most of my favorites. :-Ç
> what do you mean ?

To be clear Krusader editor, kwrite, kate, ... are fine
Or any other favorite editor, the choice of the editor is up to you, not me ;)
But you have to disable the automatic formatting stuff first,
and test it with:
- file, save as
- check the filesize
- diff foo foo_save_as
So that you are realy shure that the automatic formatting stuff is turned off.

In the past i thought that i turned off the automatic stuff but dit
not check filesize
and the diff to confirm it, so i skrewed it up several times :-)

Frank

[Richard/g]

El Vie 01 Jul 2005 04:16, Frank Schoolmeesters escribió:
> On 7/1/05, Frank Schoolmeesters
<frank.scho...@gmail.com> wrote:
> > On 7/1/05, Richard/g <richar...@gmail.com> wrote:
> > >
> > > OK, just turned off most of my favorites. :-Ç
> >
> > what do you mean ?

Well, I suppose because I like the automatic features. :-)

> These are the settings for the Krusader editor:
> a) Settings->Configure Editor->Editing
> disable "Static Word Wrap"

Agree. Mine is always disabled.

> b) Settings->Configure Editor->Indendation
> *disable automatic indendation
> *disable indendation with spaces

I like auto-indent. Been using it since TurboPascal v1. And I
used to use it with spaces from habit to avoid an obscure error
in some forgotten compiler version. I still have a Tab key, so
no problem.

> c) Settings->Configure Editor->View Defaults
> disable dynamic wordwrap for readability (recommended)

I like this because it allows leaving the text in html <p></p>
blocks contiguous so that they wrap to fit the available space,
regardless of the size of the viewers screen. Would have thought
it would serve the same function in docbook, but I guess not.

Actually, I thought it only affected the visual representation
and had no effect on the actual text?

Anyway, I can adapt.

regards,
Richard.

[Frank Schoolmeesters]

On 7/1/05, Richard/g <richar...@gmail.com> wrote:
>
> El Vie 01 Jul 2005 04:16, Frank Schoolmeesters escribió:
> > On 7/1/05, Frank Schoolmeesters
> <frank.scho...@gmail.com> wrote:
> > > On 7/1/05, Richard/g <richar...@gmail.com> wrote:
> > > >
> > > > OK, just turned off most of my favorites. :-Ç
> > >
> > > what do you mean ?
>
> Well, I suppose because I like the automatic features. :-)
>
> > These are the settings for the Krusader editor:
> > a) Settings->Configure Editor->Editing
> > disable "Static Word Wrap"
>
> Agree. Mine is always disabled.

This is what kills the formatting :-)
always OFF

> > b) Settings->Configure Editor->Indendation
> > *disable automatic indendation
> > *disable indendation with spaces
>
> I like auto-indent. Been using it since TurboPascal v1. And I
> used to use it with spaces from habit to avoid an obscure error
> in some forgotten compiler version. I still have a Tab key, so
> no problem.

This depends,
use for indentation always spaces (and NOT tabs).
You can use automatic indendation if you want, but you need to test it,
and see what happens.
But usually you need to add/remove manually some spaces,
to make it "human readable"

The problem is that many editors use different words for the same thing
in the config window :)
So it can be a bit confusing to configure it right.

> > c) Settings->Configure Editor->View Defaults
> > disable dynamic wordwrap for readability (recommended)
>
> I like this because it allows leaving the text in html <p></p>
> blocks contiguous so that they wrap to fit the available space,
> regardless of the size of the viewers screen. Would have thought
> it would serve the same function in docbook, but I guess not.
>
> Actually, I thought it only affected the visual representation
> and had no effect on the actual text?

yes, it is.
That is why i have used "recommend", i have turned it off, but it can
be turned on.
But it might cause confusion when it is turned on,
when long lines are used where <enter> is not allowed.
e.g. installation.docbook in some parts of the installation procedure


Sorry if the note was a bit unclear.

Use

- file, save as
- check the filesize
- diff foo foo_save_as

to test your editor, and it should be ok ( i hope :-)

Frank

[W. T. Fudoki Wilkinson]

Is Kate OK?  Actually I use Kate for just about everything.

terry

On 7/1/05, Frank Schoolmeesters <frank.scho...@gmail.com> wrote:

[Frank Schoolmeesters]

On 7/1/05, W. T. Fudoki Wilkinson <fudoki.w...@gmail.com> wrote:
> Is Kate OK? Actually I use Kate for just about everything.
>
> terry

Yes, sometimes i use kate too,
it depends of in what mood i'm an what is the wheater outside ;-)
There are so many text editors ...

Just
- disable "Static Word Wrap"
- if you use automatic Indendation, use only spaces and NOT tabs
- disable dynamic wordwrap for readability (recommended)

Use
- file, save as
- check the filesize
- diff foo foo_save_as
to test your editor, and it should be ok ( i hope :-)

See my previous mail to Richard for more details (Date: Jul 1, 2005 3:40 PM)

Frank

[W. T. Fudoki Wilkinson]

Think I have a new "favorite" editor (of the dozen or so on my computers)!!!  It came with "Sarge" and is called "Leafpad".  It's really fast and simple.  Like the best M$ program, Notepad.  I used to put the graphic below on my websites I did for customers - and it was not a joke!!!

On 7/1/05, Frank Schoolmeesters <frank.scho...@gmail.com> wrote:

[Frank Schoolmeesters]

If you would use the M$ program Notepad, the filesize will change because
it converts the end-of-line chars from Unix to dos format ;-)

Like i have already mentioned there are gazillion editors,
disable "Static Word Wrap" and check how the indendation works.
And check the
filsize and
diff foo1 foo2
and it should be ok.

Just dit take a fast look:
http://tarot.freeshell.org/leafpad/
http://freshmeat.net/projects/leafpad/

Frank

On 7/4/05, W. T. Fudoki Wilkinson <fudoki.w...@gmail.com> wrote:
> Think I have a new "favorite" editor (of the dozen or so on my computers)!!!
> It came with "Sarge" and is called "Leafpad". It's really fast and simple.
> Like the best M$ program, Notepad. I used to put the graphic below on my
> websites I did for customers - and it was not a joke!!!
>
>
>

[W. T. Fudoki Wilkinson]

See below:

On 7/5/05, Frank Schoolmeesters <frank.scho...@gmail.com> wrote:

If you would use the M$ program Notepad, the filesize will change because
it converts the end-of-line chars from Unix to dos format ;-)

Yep - so even the best M$ program is not good enough to use in *nix!

Terry

[Jonas Bähr]

Am 20.07.2005 um 11:47 schrieb W. T. Fudoki Wilkinson:

See below:

On 7/5/05, Frank Schoolmeesters <frank.scho...@gmail.com> wrote:

If you would use the M$ program Notepad, the filesize will change because
it converts the end-of-line chars from Unix to dos format ;-)

Yep - so even the best M$ program is not good enough to use in *nix!

I recommend MetaPad http://www.liquidninja.com/metapad/

It's as small and fast like notepad, can be used with TC on F4, exits with Esc, can deal with Unix, Win and Mac lineendings, Big-/Little-endian unicode, autoindention....

you should give it a try...

Jonas

[Frank Schoolmeesters]

I personally use the Krusader editor, Kwrite or Kate.
Because I like the syntax highlighting of the docbook tags.
I suppose Metapad has no syntax highlighting (not shure)
http://www.liquidninja.com/metapad/metapad.gif

Anyway, use the editor that you like.
The most important is that you deactivate the "Static Word Wrap"
so that you not *skrew up* the human readability.
Watch out with automatic indendation: only spaces, no tabs.
Optional: disable dynamic wordwrap for human readability

Like explained several times before, use your favorite editor.
Open a docbook file, "save as" the docbook file.
- check the filesizes
- check $ diff file file_save_as
when both are equal, the editor setings should be ok.

Frank

[Richard/g]

El Wed 20 Jul 2005 08:29, Jonas Bähr escribió:
> Am 20.07.2005 um 11:47 schrieb W. T. Fudoki Wilkinson:
> > See below:
> >
> > On 7/5/05, Frank Schoolmeesters
> > <frank.scho...@gmail.com> wrote:
> >
> > If you would use the M$ program Notepad, the filesize will
> > change because
> > it converts the end-of-line chars from Unix to dos format
> > ;-)
> >
> > Yep - so even the best M$ program is not good enough to use
> > in *nix!
>
> I recommend MetaPad http://www.liquidninja.com/metapad/
> It's as small and fast like notepad, can be used with TC on
> F4, exits with Esc, can deal with Unix, Win and Mac

> lineendings, Big-/Little- endian unicode, autoindention....

>
> you should give it a try...

I second it!
I keep TotalCommander and Metapad together on a utilities disk
because wherever I need TC I also need Metapad. I think the
version I use is 3.5. Don't remember about highlights but it is
much, much better than notepad and very lightweight and fast for
it's size.

Richard.

[W. T. Fudoki Wilkinson]

I'll add it to my editor collection!  Thx!

terry

On 7/20/05, Jonas Bähr <jonas...@web.de> wrote: