Re: A writer for PreTeXt

[BP Jonsson <bpjonsson-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

You need to familiarize yourself with how different elements are 
represnted in the Pandoc AST.  In my experience the best way to do 
that is not to read the documentation (althou8gh you want to do 
that too of course[^1]) but to type examples of the kinds of 
structures you want to work with in Markdown and study what they 
look like in native and json output.  A JSON prettyprinter which 
adds spacing and indentation is a very good help.  Start with 
simple things like `[text]{#id .class1 .class2 attr1=val1 
attr2=val2}` and go in to more complicated/nested structures once 
you understand them.

To help me with visualizing the Lua objects I use the table 
dumping function[^2] from the Penlight libraries[^3] enhanced by 
the following custom function which makes a copy of (the 
non-metatable parts of) the lua objects, adding a key for the 
element type which otherwise is buried in the metatables:

````lua
local pl_pretty = require "pl.pretty"

-- visualize a (tree of) Lua Pandoc elements
-- without destroying the originals
function showit (x)
     if 'table' == type(x) then
         local y = {} -- the "copy"
         for k, v in pairs(x) do
             y[k] = showit(v) -- expand recursively
         end
         -- show the tag from the metatable
         if y._t then
             -- if y._t already exists (it shouldn't) don't clobber it
             y._t = { _t = y._t, t = x.t }
         else
             -- otherwise just assign the value of x.t from the 
metatable to it
             y._t = x.t
         end
         return y
     else
         return x
     end
end

function dumpit (x)
     pl_pretty.dump(showit(x))
end
````

I have these living in my `~/.pandoc/init.lua` so that they are 
always available.  Saying `dumpit(element)` will then pretty-print 
the element structure to stderr.

[^1]: Above all the Lua filter documentation
     <http://pandoc.org/lua-filters.html#lua-type-reference>
     but also the element type definitions (which were all we had 
before the advent of lua filters.
 
<http://hackage.haskell.org/package/pandoc-types-1.17.5.4/docs/Text-Pandoc-Definition.html#t:Pandoc> 

     (may not be the latest version).

[^2]: 
<http://stevedonovan.github.io/Penlight/api/libraries/pl.pretty.html>

[^3]: <https://github.com/stevedonovan/Penlight>

Den 2019-04-11 kl. 06:43, skrev Oscar Levin:
> Hi John,
> 
> Thanks for the hint.  I've been trying to wrap my head around all this
> (filters and their relation to custom writers, plus the logical structure
> of how the writer "walks" the AST, if that is even the right way of
> thinking about it), so far with little luck.  Maybe I'm stuck in the
> mindset of how xslt processes xml.  I'll keep hacking away.
> 
> I found an old custom JATS writer, but that seems abandoned (since there is
> regular writer for it now): there sections were handled by putting
> </section><section> where headers go, and then removing the first
> </section> and adding one at the end of the document.  That approach would
> not work for me, since I would like <subsection>.  I assume the
> hierarchicalize would allow for this?  So far I've been unable to figure it
> out though.
> 
> While I keep thinking about this, here is a little more about PreTeXt.  I'm
> not the author of it, but as I see it, the big advantage over docbook is
> math support (it was previously called MathBook XML).  I like it for my
> textbooks because it allows for theorems/proofs, and exercises/solutions,
> and so on.  The HTML output you get (via xslt) can put solutions or proofs
> in "knowls": a link you click on that expands a box with the content.
> Cross references also work this way (if you reference an earlier theorem,
> clicking on the link opens a box with the statement of the theorem, for
> example).  You can also process the xml into LaTeX for pdf output.
> 
> In terms of users, I can only speculate on lower bounds: the "gallery" of
> textbook projects on the PreTeXt website lists 33 completed books, and I
> know of at least a dozen more books currently under development.  The
> github repository (https://github.com/rbeezer/mathbook) has been forked 82
> times.  I'm not sure what you would consider a reasonable number of users;
> I would like to see the number of users grow, and I see having an easy way
> to get people started by converting a latex or word document into PreTeXt
> as a good step in that direction.
> 
> Thanks,
> Oscar.
> 
> On Friday, April 5, 2019 at 11:27:19 AM UTC-6, John MacFarlane wrote:
>>
>>
>> To group content into sections, you should be able to
>> use the function hierarchicalize from pandoc.utils:
>>
>> https://pandoc.org/lua-filters.html#utils-hierarchicalize
>>
>> This wraps the function that the Haskell writers use.
>>
>> A regular writer might be considered, but I'd like to
>> know more about PreTeXt.  What is the advantage over
>> using, say, plain DocBook?  How many users are there?
>>
>> Oscar Levin writes:
>>
>>> I am working on a custom (lua) writer for PreTeXt (
>> https://pretextbook.org/),
>>> which I use to write open math textbooks.  In terms of syntax, PreTeXt
>> is
>>> xml and  is very similar to docbook, so a lot of what I need was easily
>>> modified from the sample.lau custom writer.
>>>
>>> What I haven't been able to figure out is how to wrap sections in
>> <section>
>>> tags.  That is, in the built in docbook writer, if you have a header, I
>>> think it creates a section with a title around the appropriate content.
>>   Is
>>> there any way to do this with a custom lua writer?
>>>
>>> Perhaps a better approach would be to contribute a new built in writer
>> by
>>> modifying the docbook writer.  I think there would be a good number of
>>> people who would find this writer useful.  Would such a contribution be
>>> considered?
>>>
>>> Thanks,
>>> Oscar.
>>>
>>
>