Flexible modular files with xpointer

[Oscar Levin]

TL;DR: any objections to me adding some suggested uses of xpointer to the Section 5.3: Modular Source Files page of the guide?  In addition, I have (and would like to continue having) xpointers as part of the CLI's "course" template.

Details:

I have long been seeking (predating pretext) a way to produce a document (say a worksheet) by itself and also have it included in a larger document (say a workbook).  Another use case: say you have a large document that contains all your favorite exam questions from many years, and you want to create an exam with a subset of those problems.

Yes, I could have a very carefully structured source directory.  Each worksheet is in its own file.  Then to produce a single worksheet, I create a new file with the "outer" structure of a pretext document and xi:include the worksheet file.  This is a little easier with the CLI's new standalone builds, but I'm still creating two files per worksheet and xincluding the worksheet in two places (the single worksheet shell and my workbook).  And what if I want to share the worksheet with my colleague: do I share two pretext files (worksheet and worksheet shell)?  Who could possibly live this way??

I think what we want in PreTeXt is for the single worksheet file to be self contained.  It is a complete document.  You can share it and it just works.  You can also xinclude the worksheet in a workbook without copy/pasting the source.  

I see two ways to make this happen: we could use existing, although sometimes dubiously supported, solutions, or we could dubiously support it ourselves.  The latter would involve something like, "whenever you try to build a pretext document that doesn't have the correct shell elements like <pretext> and <article>, we silently insert those so you get a valid build."  

The better (I think) solution is to use `xpointer` as an attribute in `<xi:include/>`.  There are some nice examples of what you could do on this wikipedia page: https://en.wikipedia.org/wiki/XPointer.  So you could write `<xi:include href="./worksheet1.ptx" xpointer="xpointer(//worksheet)"/> and get every `<worksheet>` element inside worksheet1.ptx inserted there.

For the exercise-bank example, you could xi:include exercises by xml:id similarly.  In fact, it seems like `<xi:include href="./worksheet1.ptx" xpointer="myxmlid"/> works to include the element with xml:id "myxmlid".

The downside to this approach is that there is limited support for all of these features.  lxml (and xsltproc) handle xpointer="xpointer(...)" just fine, but I think this is the only xsl processing software that has implemented the xpointer language; the langue is only a W3C draft (since 2001).  However, the xpointer framework, that allows you to have an `@xpointer`, and the `element(...)` mechanism are W3C recommendations, so have broad support.  It appears that the only real downside to only recommending use of `element()` or just a bare xml:id as the value of the `@xpointer` is that you need to always have an xml:id, rather than just referring to types of elements.

What do you think?

[Mitch Keller]

I like this idea. I wanted to go down this path with our UW worksheets project this spring, but the shortage of documentation on xpointer combined with onboarding someone totally new to PreTeXt made it too cumbersome for me to get a handle on it. However, I think with some good documentation, I could easily go through and update our repo to use it consistently.

For something like a worksheet, I think it makes a lot of sense to author in files that can be built on their own (without special interpolation from the CLI to wrap in something like an article) but that can easily be included into a larger collection. Then you can get the PDF version of a single worksheet quickly to print for class but also build an accessible online repository of all your worksheets in HTML.

--
You received this message because you are subscribed to the Google Groups "PreTeXt development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pretext-dev...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/f2a22781-e5c5-4e35-b28b-d020259da4fdn%40googlegroups.com.

-- 
Mitch Keller
mi...@rellek.net

http://www.rellek.net/