[publican-list] Machine-readable meta-data in docbook

Jeffrey Fearn jfearn at redhat.com
Wed Aug 25 03:11:48 UTC 2010


Joshua Wulf wrote:
>>> The root element of the docbook files I need to annotate are 
>>> <variablelist>, <procedure>, <table> and possibly some other at a 
>>> similar level. Anything down there that might be useable?
>>
>> If it's just to check automated access to metadata at semi-random 
>> places, why not use a remark that contains a key=value formatted 
>> string and role to identify it's use? Remark has a pretty wide range 
>> of places it can appear.
>>
>> e.g. <remark role="metadata">author="Dave Dude" verified=false 
>> created=20100127</remark>
>>
>> This way in debug mode you'd get to see where these things are set and 
>> what their values are.
>>
>> If you need even wider usage an alternative would be to use a similar 
>> key=value system, but use a common attribute that isn't currently 
>> used, Security, UserLevel and Vendor stand out. These can be used in 
>> any tag, but you lose the ability to easily see the values in the 
>> output and you are more constrained in what content you can put in an 
>> attribute.
>>
>> e.g. <table vendor="author='Dave Dude' verified=false">
>>
>> It's not as tidy as using tags, but string manipulation is not a great 
>> barrier and it works around a few harder problems that you probably 
>> don't need to solve atm. If you are using machine generation to set 
>> and get the content you can just use string serialization to pack and 
>> unpack the content.
>>
>> Cheers, Jeff.
>>
> 
> Sounds good.
> 
> Atm we have SHOW_REMARKS as an option. Could we filter that on role for 
> remarks, to allow metadata to be or not to be shown when remarks are 
> enabled? At the moment remarks are used for communicating with QE.

If it turned out that this was the way things were definitely going to 
be used we'd do that. Once you have a demo of what you want someone 
might come up with a much better way of doing it than using remarks though.

In the mean time you could use the condition attribute in the remark so 
it gets ignored when sending content to QE.

A more generic RFE would be for SHOW_REMARKS to be tied to UserLevel, 
with only remarks with UserLevel <= SHOW_REMARKS being displayed. Then 
you can set SHOW_REMARKS=1 but set UserLevel=2 in the metadata remarks, 
and other people could use it with other work flows.

Cheers, Jeff.

-- 
Jeff Fearn <jfearn at redhat.com>
Software Engineer
Engineering Operations
Red Hat, Inc
Freedom ... courage ... Commitment ... ACCOUNTABILITY




More information about the publican-list mailing list