Autodoc XML manual for people making extractors of their own
Imported from http://bugzilla.roxen.com/bugzilla/show_bug.cgi?id=1632
Reported by Johan H Sundström, IDA jhs@pike.ida.liu.se
A detailed-enough description of the XML format the autodoc mk ii extractor outputs after crawling the pike tree for people who want to make extractors for their own documentation formats is neecessary. Such a manual should at least give sufficient information about:
-
the markup used for grouping entities or their different signatures with the corresponding documentation string
-
the intent/semantics of all tags (perhaps as a simple extension to the current docs for the autodoc level markup tags, listing how they would show up in the XML output by the autodoc extractor)
-
the restrictions imposed on the output format (as dictated by a DTD or XSchema ruleset), preferrably in some machine-readable state, to be used for compliance verification (so we don't end up with various part-broken documentation, that only barely works in some random manual subset, e g the HTML docs but not the PDF version)
preferrably aimed at people unfamiliar with, or indeed even fundamentally opposed to learning all the nitty-gritty details of our own autodoc level syntax (since these are the people who will most likely be writing their own extractors; know thy audience ;-).
This ticket most likely ought to be split-up into sub tickets, similar to [bug #882], but I'll leave that to the assignee, who is better equipped to partitioning the workload.