Open Stack

On 10/31/2013 08:44 AM, Steve Gordon wrote:
>> as in this case, we are talking about living documents; are you
>> proposing inserting the markers directly into the XML?
> 
> I think we would have to handle this in the transformation and ultimately the output (via JavaScript and an external data source/provider) rather than the source XML - after all we're hopefully not going to rebuild the guide every time somebody posts a relevant question.

Yes, I'm assuming it would have to work the way Disqus currently does.

>> If not, how will you track the specific paragraph between versions?
> 
> I don't think we can (realistically) go down to the paragraph level 

+1 I wonder about the return of being that granular. To pull it off,
we'd have to require xml:ids on all things that could be commented on
independently (para, figure, informalfigure, table...)

> but we (almost?) always have an ID at the section level to key off. I think this might have been a requirement, in addition to the book level identifiers, for the existing disqus stuff to work?

That's correct, currently an xml:id is required on anything that could
become a chunk. It won't build otherwise.

...
>> Eventually it led to a significant number of authors choosing to use a
>> format similar to RST instead, (where ID values were even MORE of a
>> problem) in order to get better readability.  Which begs the question,
>> what about our docs that are already in RST?
> 
> These get converted to DocBook XML in an intermediate step, and ultimately are run through the same transforms as the rest of the guides to produce the output. Anything we applied in the transformation for the other guides would apply to these too. As you note identifiers might be problematic as while there are some they don't appear (looking at the HA guide) to be as frequent/consistent - looking at the structure of the existing identifiers in the HA guide it may even be possible to automate generation of these though.

I haven't looked at any of that, but as long as you have a mechanism for
associating stable ids with sections, chapters, etc, it should work. A
challenge of light markup languages is that you don't have attributes or
"info" elements which aren't presented into which you can stick
metadata. You have to invent an alternative without making it ugly and
brittle.

Regards,
David