84 lines
4.7 KiB
Markdown
84 lines
4.7 KiB
Markdown
# Notes on automatic reference page generation
|
|
|
|
Main takeaway point: ref page generation from the spec sources is ready to
|
|
go. It can be tweaked in lots of small ways, but as it stands it's a huge
|
|
improvement over the current ref pages and should be adopted ASAP.
|
|
|
|
## Approach
|
|
|
|
This is done with some Python scripts that rely on the rigid structure
|
|
we've enforced on command and structure definitions in the spec. Everything
|
|
from the paragraph *preceding* the protos/structs include:: through the
|
|
validity:: include is pulled out and then split up into ref page sections.
|
|
In some cases, it isn't immediately obvious how to reorder to get all the
|
|
content relevant to a single command or struct blocked together in this
|
|
fashion, and some simplistic semantic tagging has been added for those cases
|
|
where the structural organization isn't appropriate.
|
|
|
|
The changes to the spec are straightforward, though they appear large in
|
|
some places. What's happening is:
|
|
|
|
* Validity includes are moved below all the relevant text.
|
|
* Structure definitions are moved after the validity includes for
|
|
commands, so they don't overlap or imbed. This has been done for
|
|
enumerant definitions in some cases, but those are harder to unwind.
|
|
* Blank lines are being removed from parameter / member definition bullet
|
|
lists, so they don't confuse the extraction script.
|
|
* Annotations in the form of asciidoc comments were added where
|
|
they were needed to assist the extraction scripts. These look
|
|
like
|
|
<br>// refBegin vkSomething short description of command for ref page title
|
|
<br>// refEnd vkSomething [list of related ref pages]
|
|
* A bunch of small consistency edits were done to match the style guide.
|
|
These (mostly) aren't directly related to the extraction process, but it
|
|
is an opportune time to do them.
|
|
* Pages that don't have extractable descriptive text in the specification,
|
|
such as Vk*Flags and some Vk*FlagBits types, get automatically generated
|
|
ref pages. These just define the interface and link to other pages using
|
|
that type.
|
|
|
|
## Things to be done
|
|
|
|
These are (more or less) in decreasing priority order. Few of them are
|
|
difficult.
|
|
|
|
* Something is messed up with the individual page generation targets in
|
|
the Makefile, so the genRef.py action isn't a dependency of
|
|
$(MANSOURCES) yet. See
|
|
https://www.cmcrossroads.com/article/rules-multiple-outputs-gnu-make?page=0%2C2
|
|
* Cross-page macro links are broken in the individual ref pages, due to
|
|
using the wrong macros, but are OK in the single-page apispec.html.
|
|
Should be easily fixed.
|
|
* manpdf (single-page PDF ref document) target is currently broken.
|
|
* Turn handle references from sname: to slink: so they link to the right
|
|
place. Consider using an hlink/hname macro instead. Similarly for
|
|
basetype: (which doesn't link, but could now with blink:/btext:). In
|
|
general, most of the ?name: macros can and should turn into ?link:,
|
|
aside from those directly in the section describing that name.
|
|
* Need to tweak asciidoc macros for man pages (manpages.conf).
|
|
* "See Also" links are automatically generated based on the type
|
|
dependencies between pages. This works well, but doesn't include logical
|
|
groupings (all clear commands, all drawing commands, etc.). These can be
|
|
added to the explicit crosslinks in // refEnd statements if desired.
|
|
* Remove autogenerated files from git and enhance the Makefiles to do all
|
|
the scripting work required to generate the ref page sources, vkapi.py,
|
|
etc. at build time.
|
|
* Some problems with a2x not finding NOTE icons from the asciidoc
|
|
distribution (worked around by copying into the man/images directory,
|
|
for now). It would sure be nice if the build were smart enough to use
|
|
the icons distributed with asciidoc, instead of needing separate copies.
|
|
* I'm not sure how to best deal with KHR extension ref pages. We could
|
|
generate them separately in their branches and combine with core pages,
|
|
or generate everything in the wsi_extensions branch - but that will
|
|
leave us with core ref pages including WSI extension material, without
|
|
any obvious indication of why or where. Changes for the KHR extension
|
|
branches will be small once the 1.0 changes are merged in, and I'll
|
|
undertake to do those once the core changes are accepted.
|
|
* Cross-page asciidoc links are broken. This is hard to fix. Probably the
|
|
best thing to do is strip \<\<\>\> links from the source, or perhaps
|
|
generate an HTML link to the live spec.
|
|
* VkResult page needs a better "See Also" section - but not the full list
|
|
of functions returning VkResult.
|
|
* Short descriptions are currently embedded in the spec source, and are
|
|
missing in some cases. Would it make more sense to add them to vk.xml?
|