D22799: Adding new .docbook for KAddressBook, draft version

[David Bryant]

On Sunday, July 28, 2019 11:08:30 PM CDT Burkhard Lück wrote:
> lueck added a comment.
> 
> Please use checkXML5 index.docbook to validate XML
> 

I have been doing that. It appears to me that checkXML5 sometimes throws 
extraneous errors. For instance, if I put in

<chapter> <title> xxx </title> </chapter> 

sometimes it gives me a validation error. So I just change it to

<chapter> <title> xxx </title> <para> blah blah blah </para> </chapter>

and then everything is fine. That seems wrong, to me.

> 
> <legalnotice>&FDLNotice;</legalnotice>
> 
> &CCBYSA4Notice; see
> https://cgit.kde.org/kdoctools.git/tree/src/template.docbook
> 

Somebody had referred me to an older copy of "template.docbook", I guess, 
because I had coded this as &FDLNotice;, as instructed. Anyway, when I make 
the suggested "correction", checkXML5 throws this error message:

david at linux-f0mc:~/Documents/KDEStuff/KAB> checkXML5 KAddressBook.docbook
KAddressBook.docbook:4: element xref: validity error : IDREF attribute linkend 
references an unknown ID "cc-by-sa-4"
kf5.kdoctools: Error: `xmllint --noout` outputted text

So for the time being I have inserted this code in my XML document, to patch 
it up (so I can run meinproc5 without getting errors).

<chapter id="cc-by-sa-4">
<title>Fake Out that &CCBYSA4Notice; Doodad for a While</title>
<para> </para>
</chapter>

but it seems to me that "template.docbook" is incomplete or inaccurate, 
because now when I run the XML to HTML conversion, I see this in the 
introductory section:

Permission is granted to copy, distribute and/or modify this document under 
the terms of the Creative Commons Attribution-ShareAlike 4.0 International or 
any later. A copy of the license is included in Chapter 6, Fake Out that 
&CCBYSA4Notice; Doodad for a While.

Where do I get a copy of the referenced license? Is it supposed to be inserted 
automatically via some new XML stylesheet? If so, how can I get a copy of the 
new stylesheet? Oh, yeah -- speaking just as an English grammar perfectionist 
right now, "the Creative Commons Attribution-ShareAlike 4.0 International" 
seems to be missing at least one word (a noun, probably "license") ... AFAIK, 
"the International" refers to an old song that was sung by the IWW about 100 
years ago, and "international" is almost always an adjective, and hardly ever 
a noun (the only exceptions being that odious old song, and a brand of trucks 
and farm implements that got bought out by Allis-Chalmers(?) years ago).

Oh -- I looked for the referenced license on-line, and found it here:

https://creativecommons.org/licenses/by-sa/4.0/legalcode

So it appears that something is miscoded ... yep, I found it, in a file named 
"ccbysa4-notice.docbook":

<xref linkend="cc-by-sa-4"/>

This ought to be replaced with 

<ulink href="https://creativecommons.org/licenses/by-sa/4.0/legalcode">at  the 
Creative Commons web site</ulink>, 

or something like that, with a few additional changes to the verbiage 
associated with &CCBYSA4Notice; (via "ccbysa4-notice.docbook"), to avoid 
saying that we're including the whole bloody mess in this document -- the 
license itself contains 2,409 words and 15,460 characters (if I copied it 
correctly). At least, I think that is what should be done. Including the whole 
CC license in each "Handbook" seems like overkill, to me.

> 
> View Inlineindex.docbook:34
> <releaseinfo>5.7.3</releaseinfo>
> 
> <abstract>
> Plesase use scheme from
> https://cgit.kde.org/kdoctools.git/tree/src/template.docbook
> 

Well, I figured I was following the template, which grants me a lot of 
latitude, imo. Anyway, I researched the documentation for all the components 
of the "PIM" suite of programs, and this is the best I can come up with:

<releaseinfo>5.7.3 (Applications 17.12.3)</releaseinfo>

Is that better? I'm running openSuSE LEAP 15.0, and I'm not ready to install a 
bunch of KDE stuff that's not in my distro. Not yet, anyway.

> 
> [big snip ... stuff about <filename> tags]
> 

Thanks for the tip on filename extensions. I'll keep that in mind.

> 
> Please add <chapter id="credits">, see
> https://cgit.kde.org/kdoctools.git/tree/src/template.docbook

Well, I said I was submitting a rough draft. Don't worry. I'll eventually add 
several more chapters. but it's going to take a while.  ◕‿◕

-- 
D. Bryant
Canyon Lake, Texas