[doc] how to use fixme?

[Diana Shannon <sh...@apache.org>]

I'm trying to understand how best to use the fixme element for adding 
comments to docs, either for authors who are willing to update their own 
work or for problems I cannot solve, at least on the first pass.

I notice fixme has a required author attribute. In document-v10.dtd, it 
states:
    the "author" attribute should match the "key" attribute of the 
<author> element

I assume this means the attribute id of a person element listed under 
document/header/authors/person. Still, I don't want to add my name as an 
author to each and every document which simply needs my fixme comments.

Should I simply use the id of the existing person listed under authors?

Thanks.

Diana


---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org

Re: [doc] how to use fixme?

[David Crossley <cr...@indexgeo.com.au>]

Diana Shannon wrote:
> I'm trying to understand how best to use the fixme element for adding 
> comments to docs, either for authors who are willing to update their own 
> work or for problems I cannot solve, at least on the first pass.
> 
> I notice fixme has a required author attribute. In document-v10.dtd, it 
> states:
>     the "author" attribute should match the "key" attribute of the 
> <author> element
>
> I assume this means the attribute id of a person element listed under 
> document/header/authors/person. Still, I don't want to add my name as an 
> author to each and every document which simply needs my fixme comments.
> 
> Should I simply use the id of the existing person listed under authors?

For now i would just use the actual name (or just initials)
of the person who thinks that a <fixme> note is necessary.
I would not worry about trying to match the value up with
other things. There is no content validation happening for
these attributes anyway. So i say do not worry, we can tidy
it up later if we want to rely on it.
--David



---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org

Re: [doc] how to use fixme?

[Stefano Mazzocchi <st...@apache.org>]

Diana Shannon wrote:
> 
> I'm trying to understand how best to use the fixme element for adding
> comments to docs, either for authors who are willing to update their own
> work or for problems I cannot solve, at least on the first pass.
> 
> I notice fixme has a required author attribute. In document-v10.dtd, it
> states:
>     the "author" attribute should match the "key" attribute of the
> <author> element
> 
> I assume this means the attribute id of a person element listed under
> document/header/authors/person. Still, I don't want to add my name as an
> author to each and every document which simply needs my fixme comments.

Hmmmm, good point.

> Should I simply use the id of the existing person listed under authors?

No, that's against the idea of fixme.

Yes, we should use something like a map (doesn't need to be a 'topic
map' to be honest)... the best thing would be to have the DTD aggregate
the committers list... but I'm not sure how to do it (and I'm not a DTD
guru, to be honest).

Suggestions anyone?

-- 
Stefano Mazzocchi      One must still have chaos in oneself to be
                          able to give birth to a dancing star.
<st...@apache.org>                             Friedrich Nietzsche
--------------------------------------------------------------------



---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org

Re: [doc] how to use fixme?

["J.Pietschmann" <j3...@yahoo.de>]

Diana Shannon wrote:
> I notice fixme has a required author attribute. In document-v10.dtd, it 
> states:
>    the "author" attribute should match the "key" attribute of the 
> <author> element
> 
> I assume this means the attribute id of a person element listed under 
> document/header/authors/person. Still, I don't want to add my name as an 
> author to each and every document which simply needs my fixme comments.
> 
> Should I simply use the id of the existing person listed under authors?

An id pointing into a topic map...sorry, couldn't resist, don't take
this too serious.

J.Pietschmann


---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org