Assuming you have all the right tools installed (see Software Dependencies below), you should be able to go to -…path-to-git-repo/vulkan/doc/specs/vulkan and:
$ make all@@ -802,9 +807,9 @@
$ make xhtml chunked pdf manhtml manpdf manpages manhtmlpages checkinc checklinks
This should generate a variety of targets under $(OUTDIR) (by default, -../../../out/). The checked-in file $(OUTDIR)/index.html links to them -all, or they can individually be found as follows:
This should generate a variety of targets under $(OUTDIR) (by default, +../../../out/1.0). The checked-in file $(OUTDIR)/index.html links to +them all, or they can individually be found as follows:
@@ -813,17 +818,17 @@
-Single-file XHTML (from a2x) - $(OUTDIR)/xhtml/vkspec.html +Single-file XHTML (from a2x) - $(OUTDIR)/xhtml/vkspec.html
-Chunked HTML (from a2x) - $(OUTDIR)/vkspec.chunked/index.html +Chunked HTML (from a2x) - $(OUTDIR)/vkspec.chunked/index.html
-PDF (from a2x) - $(OUTDIR)/pdf/vkspec.pdf +PDF (from a2x) - $(OUTDIR)/pdf/vkspec.pdf
-Single-file HTML - $(OUTDIR)/apispec.html +Single-file HTML - $(OUTDIR)/apispec.html
-File-per-entry-point HTML - $(OUTDIR)/man/html/* +File-per-entry-point HTML - $(OUTDIR)/man/html/*
-File-per-entry-point nroff source - $(OUTDIR)/man/3/* +File-per-entry-point nroff source - $(OUTDIR)/man/3/*
List of commands, structs, etc. missing from the API spec - - $(OUTDIR)/checks/notInSpec.txt + $(OUTDIR)/checks/notInSpec.txt
-Validator script output for API spec - $(OUTDIR)/checks/specErrs.txt +Validator script output for API spec - +$(OUTDIR)/checks/specErrs.txt
Validator script output for reference pages - - $(OUTDIR)/checks/manErrs.txt + $(OUTDIR)/checks/manErrs.txt
We strongly sugges that once you have the basic build working, you use e.g. --j 8 (or other appropriate number depending on the number of cores in your -CPU) to parallelize the reference page builds, since there are so many of -them.
If your asciidoc installation does not put the stylesheets and xsl files in -the standard /etc/asciidoc/dblatex directory, set the environment variable -DBLATEXPREFIX to the path to that directory (the one containing the -asciidoc-dblatex.xsl and asciidoc-dblatex.sty installed with asciidoc).
If you are just testing asciidoc formatting, macros, stylesheets, etc., you -can edit test.txt, which is a stripped-down version of vkspec.txt, -and build an alternate version of the spec with either
We strongly sugges that once you have the basic build working, you use e.g.
$ make TOPDOCHTML=test.txt xhtml+
$ make -j 8
or the simpler
tmake xhtml-
This example will generate the file $(OUTDIR)/xhtml/test.html . Note that -TOPDOCHTML only applies to the xhtml and chunked targets at present.
(or other appropriate number depending on the number of CPU cores you have) +to parallelize the reference page builds, since there are so many of them.
If your asciidoc installation does not put the stylesheets and xsl files in +the standard /etc/asciidoc/dblatex directory, set the environment variable +DBLATEXPREFIX to the path to that directory (the one containing the +asciidoc-dblatex.xsl and asciidoc-dblatex.sty files installed with +asciidoc).
If you are just testing asciidoc formatting, macros, stylesheets, etc., +we suggest editing vkspec.txt to comment out most of the chapter +includes.
In addition to the XHTML and PDF targets, there is also a single-file HTML5 -target, html, which generates output directly from asciidoc without going +target, html, which generates output directly from asciidoc without going through Docbook. This is somewhat quicker to generate, but formatting and section numbers aren’t consistent with the other builds and it is not for -publication - just testing. The html target will generate the file -$(OUTDIR)/html/vkspec.html .
There are some images in the images/ directory which are maintained in one +
There are some images in the images/ directory which are maintained in one format but need to be converted to another format for corresponding types of output. Most are SVG converted to PDF, some are PPT converted to PDF converted to SVG. SVG and PDF forms are needed for the HTML and PDF output formats, respectively.
These files are not automatically converted by the Makefile. Instead, all -output forms required are checked into images/ . On the rare occasions that -someone changes a source document and needs to regenerate the other forms, -go into images and make in the directory.
cd images +make+
The supported macros are defined in config/vkspec.conf (for the API spec) -and config/manpages.conf (for the reference pages).
Tags used in both the specification and reference pages:
-flink:vkBlah - the name of an API command. -
--fname:vkBlah - the name of an API command. -
--ftext:anything - the name of something that looks like an API command, but - isn’t (wildcards like ftext:vkCmd*). -
--slink:VkBlah - the name of an API C structure, handle, or scalar type. The - slink:VkBlah.membername syntax is not currently supported. -
--sname:VkBlah - the name of an API C structure, handle, or scalar type. The - notation sname:VkBlah.membername is also allowed where that makes sense - (NOTE: VkBlah.membername is not properly validated at present). -
--stext:anything - the name of something that looks like an API structure, - handle, or scalar type, but isn’t (wildcards like stext:Vk*CreateInfo). -
--elink:VkBlahFlags - the name of an API C "enum" type (bitmask or - enumeration). -
--ename:VK_BLAH - the name of an API enumeration or #define token. -
--etext:anything - the name of something that looks like an API "enum" type, - enumeration or #define token, but isn’t (wildcards or partial token names, - like etext:BC5). -
--pname:param - the name of a command parameter or struct member being - documented -
--basetype:type - the name of a base scalar type, such as basetype:VkBool32. -
--code:varname - the name of a shading language variable -
-Tags used only in the specification, at present:
-can:, cannot:, may:, maynot:, must:, mustnot:, optional:, recommend:, - required:, should:, and shouldnot: - used to tag places in the spec where - these terms are used in accordance with their definitions in section 1.3 - "Terminology". They do not currently do anything but expand to their names - (adding a space for e.g. mustnot: → must not), but may be used to - generate an index or some visual indicator in the future. -
-The [efs]link: macros are used for validation, and are also expanded into -xref links to the correspondingly named anchor.
The [efsp]name: macros are used for validation, but are not expanded into -links.
The [efs]text: macros are not used for validation, and are not expanded into -links.
The supported macros are defined in config/vkspec.conf (for the API spec) +and config/manpages.conf (for the reference pages).
The tags used are described in the style guide (styleguide.txt).
We will eventually tool up the spec and ref pages to the point that anywhere -there’s a type or token referred to, you could click/hover on it in the HTML -view and be taken to the definition of that type/token. That will take some -more plumbing work to tag the stuff in the autogenerated include files, and -do something sensible in the spec (e.g. resolve links to internal -references).
In that light, the [fs]name: vs. [fs]link: distinction seems mostly -unneeded. Probably the only time we would not want a tag to be a link to its -definition is when tagging a function name inside its own ref page. So once -the plumbing is done, most of the [fs]name: tags can turn into [fs]link: -tags.
The ename: vs. elink: distinction is different since they’re referring to -different namespaces - individual enumerant names vs. "enum" type names - -rather than different ways of presenting the same command or struct name as -for the other tags.
Most of these macros deeply need more intuitive names.
Prior to the 1.0.20 update of the API spec, the reference pages in man/ +were handwritten, incomplete, and often way out of date with respect to the +spec.
Our initial effort to address this was to tag the API spec to help identify +boundaries of language talking about different commands, structures, +enumerants, and other types, then use a set of Python scripts to +automatically extract that language into the corresponding ref page. Pages +without corresponding content in the API spec are generated automatically, +when possible.
This has generated a semantically complete set of ref pages. Although they +are still far from ideal, they now fully document the API, and will stay in +sync with it. A significant drawback of this approach is that the only place +ref pages for extension interfaces can be generated is inside the +corresponding extension branches.
If for some reason you want to regenerate the ref pages from scratch +yourself, you can do so by
$ rm man/apispec.txt +$ make apispec.txt+
The genRef.py script will generate many warnings, but most are just +reminders that some pages are automatically generated. If everything is +working correctly, all the man/*.txt files will be regenerated, but their +contents will not change.
This branch introduces a Vulkan-specific XHTML CSS stylesheet -in config/vkspec-xhtml.css. Mostly it just clones the default +in config/vkspec-xhtml.css . Mostly it just clones the default Asciidoc stylesheet, but adds some new features:
There is the start of support for marking added, removed, and changed text in the spec body. Currently this is supported only in the XHTML targets -(xhtml and chunked), and only for paragraphs and spans of words.
Added, removed, and changed material is marked with the asciidoc roles named added, removed, and changed respectively. They can be used to mark an entire paragraph, as follows:
There is support for marking normative language in the document. Currently -this is supported only in the XHTML targets (xhtml and chunked).
Normative language is marked with the asciidoc role named normative. It can be used to mark entire paragraphs or spans of words, in the same fashion as change markings (described above). In addition, the @@ -1107,10 +1040,10 @@
-The special characters < > & can currently be used only in +The special characters < , > , and & can currently be used only in [latexmath] block macros, not in latexmath:[] inline macros. - Instead use \lt for < and \gt for >. & is an alignment construct for - multiline equations, and should only appear in block macros anyway. + Instead use \lt for < and \gt for >. & is an alignment construct + for multiline equations, and should only appear in block macros anyway.
For example, in chapter synchronization.txt:
For example, in chapter synchronization.txt:
Cross-references to those anchors can then be generated with, for example,
You can also add anchors on arbitrary paragraphs, using a similar naming scheme.
Anything whose definition comes from one of the autogenerated API include -files ({protos,flags,enums,structs}/*.txt) has a corresponding anchor whose -name is the name of the function, struct, etc. being defined. Therefore you -can say something like:
Fences are used with the +++<<vkQueueSubmit>>+++ command...@@ -1172,10 +1106,10 @@
These are versions of required tools in Jon’s development environment -(Debian 8, shown as Debian package names). Earlier versions may work but -unless they are verified by someone else, there’s no way to know that. Later -versions should work.
These are versions of required tools in one of the editors' development +environment (Debian 8, shown as Debian package names). Earlier versions +may work but unless they are verified by someone else, there’s no way to +know that. Later versions should work.
@@ -1194,15 +1128,11 @@
-Python LXML library (python-lxml, version: 3.4.0-1) -
-Git command-line client (git, version: 2.1.4) Only needed if regenerating specversion.txt. Any version supporting the - operations git symbolic-ref --short HEAD and git log -1 - --format="%H" should work). + operations + — git symbolic-ref --short HEAD and + — git log -1 --format="%H" should work).
+2016/07/10 - Update for current state of spec and ref page generation. +
+2015/11/11 - Add new can: etc. macros and DBLATEXPREFIX variable.