[kde-doc-english] Re: formatting question for <author> sections

[Jack]

On 2011.07.05 15:57, Jack wrote:
> Hello,
> 
> While preparing a new version of the KMyMoney handbook, I've noticed
> that the <author> sections are not consistent, in that some use  
> entities
>    <author> &author.name; &author.name.mail; </author>
> and some are fully written out
>    <author>
>      <firstname>author</firstname>
>      <surname>author</surname>
>      <affiliation>
>        <address><email>author at wherever.net</email></address>
>      </affiliation>
>    </author>
> 
> What I find interesting, is that in the first case, the displayed  
> handbook page only has the author's name, not his email address, but  
> in the latter case, it shows both name and email.  I've tried several  
> variations, and the email address only shows up with the full  
> <affiliation><address><email> format.  (The .mail entities are all  
> defined with just <email>user at host</email>.)
> 
> I suppose it is not really important whether an author's email  
> address shows up at chapter and section headings, but I like  
> consistency, and I'm curious if this is a known issue and whether  
> there is any point in adding <affiliation><address> around the  
> <email> either in the contributor.entities file, or just within the  
> <author> sections in the docbook files.

Sorry to respond to my own post so quickly, but it turns out adding  
<affiliation><address> around the &author.name.mail; entity will not  
work, because most/all &author.name; entities are defined with  
<personname>.

I don't know it this has changed with different docbook dtd versions,  
but as I read the error messages, you can have either
  <personname>...</personname><email>
or
   
<firstname>...</firstname><surname>...</surname><affiliation>...</affiliation>

This is the same issue I found trying to add <contrib> to <author>  
sections in the docbook file for the man page.  It is apaparently not  
legal with <personname> but OK with all the pieces that were within the  
<personname>.  Given this, I wonder if this would be a reason to remove  
<personname> from all contributor entities.

Jack