On Wed, 09 Mar 2016, Dan Allen <dan@xxxxxxxxxxxxx> wrote: > On Tue, Mar 8, 2016 at 6:58 AM, Jani Nikula <jani.nikula@xxxxxxxxx> wrote: > >> I need to look into this again. Is there a specific option or directive >> to produce split output for includes? When I tried this, the result was >> just one big output file. (And indeed we'd need both. Some includes we >> want embedded, some includes should produce separate outputs.) >> > > Nope. What I'm saying is that you run Asciidoctor on each sub-master > include file (an include that manages a part or chapter). That gives you > your individual part/chapter files. Then you need to make an index page, > probably by using the Asciidoctor API to itemize all the chapters as a list > or something. Bummer. Getting the inter-document cross references right may become tricky. We'll be generating plenty of snippets of lightweight markup from source code documentation comments. At the time of processing, we won't know where e.g. a specific function to be cross referenced is documented, if at all. We can't require the documentation comment writers to figure that out either; it's too burdensome, too ugly in the code, and they'll bitrot quickly. Cross referencing in the asciidoc proofs of concept have worked because they've all done the processing as a single single unit, with includes. These hacks have also ignored any broken links, and there have been > Yes, it does require some thinking about cross references. There is a lot > more we can do out of the box, but all those references can be fixed with a > little bit of post-processing in the meantime. It seems to me Sphinx provides much better support regarding cross references, out of the box, within documents and to external documents (intersphinx), with target roles and domains, including validation and not creating broken links in the output. Looking at the current hacks we have for post-processing references, I'm really not thrilled about the prospect of keeping or redoing that. See how this works in Jon's Sphinx test [1]. At the time of generating the markup from source comments, there is no idea if and where gem_init_hw() and intel_guc_ucode_init() are documented. Indeed, documentation for the former does not exist, but there's no broken link. BR, Jani. [1] http://static.lwn.net/kerneldoc/gpu.html#c.intel_guc_ucode_load -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
