Additional Documentation Project

[Jason Siefken]

PreTeXt is currently missing programmer-style documentation. E.g., a website where you, already being familiar with the PreTeXt ideas, can look up in an exhaustive list what every element is, what their options are, and see examples of the output produced by various options is. I've been working on a solution!

I present: https://siefkenj.github.io/pretext-book/docs

This site is missing most of the content, but an important feature is a searchable reference of all tags

https://siefkenj.github.io/pretext-book/docs/reference/all-tags

Most of the current entries are just stubs waiting to be filled, but I wrote an entry for the <ul> tag:

https://siefkenj.github.io/pretext-book/docs/reference/elements/ul

Some features:
 - Attributes for a tag are automatically extracted from the schema
 - Allowed parents and children are automatically extracted from the schema
 - Examples show source code and have a preview of what the source looks like when rendered. These fragments of example code are automatically extracted and compiled by PreTeXt; the rendered result is then included in the documentation
 - There is an "Edit this page" button (if your screen is wide enough) that takes you to the exact github file to edit to change/improve the documentation
 - Fast. You'll notice page loads are significantly faster than the HTML produced by PreTeXt
 - Full text search.

Unfortunately, right now, this documentation is written in markdown (technically MDX which is markdown that includes JSX syntax). The Nextra framework I'm using to produce these docs uses Markdown as a basis. This could be changed with a fair amount of effort (though PreTeXt with JSX syntax included is probably a project no one wants...)

If anyone would like to help improve this documentation, pull requests are welcome!
The root repository is here:
https://github.com/siefkenj/pretext-book

[Joseph DiMuro]

Your timing on this announcement may not have been so good, Jason. A lot of us have our minds on the small documents workshop right now, including myself. :-) Your work looks great, and I think that something like this could be very helpful. But that's all I want to say right now; I don't want to ponder this one any further until after the workshop. :-)

[Rob Beezer]

Dear Jason,

I like this a lot! And have been hoping for some time to have something better
than our current "schema browser".

https://pretextbook.org/doc/schema/

because (a) it costs money, (b) it is hard to configure, and (c) it has a
shortcoming (see below).

A couple of twists:

1. I suppose you have thought of (i) rebuilding on a push to the repository
that contains changes to the schema (yes, I know what I'm asking for here!), and
(ii) testing the examples against the schema (as the schema evolves?).

2. Maybe less obvious. RELAX-NG lets you "condition" on attributes. In other
words, an element could have two descriptions, with different possible
attributes (and their values?), and accordingly have different collections of
children. (I think.)

We convert to a W3 Schema (*.xsd) to feed the tool that creates the browser
linked above. But this other schema lacks this sort of expressive power. So
the conversion emits messages about "approximating", and hence the link above
has material is not entirely accurate. Of course, I can't find, or remember, a
good example. But here is one example.

An #li can be raw text, or structured with #p, etc., so very different sorts of
children. The former scenario does not allow a @component, while the latter one
does. That is not really intentional, just an accident of recycling certain
patterns instead of making new ones. But I think there are cases where it is
intentional.

Looking forward to discussing this more.

Rob

[Jason Siefken]

On 7/12/24 7:00 PM, 'Rob Beezer' via PreTeXt development wrote:

Dear Jason,

I like this a lot!  And have been hoping for some time to have something better than our current "schema browser".

https://pretextbook.org/doc/schema/

because (a) it costs money, (b) it is hard to configure, and (c) it has a shortcoming (see below).

A couple of twists:

1.  I suppose you have thought of (i) rebuilding on a push to the repository that contains changes to the schema (yes, I know what I'm asking for here!), and (ii) testing the examples against the schema (as the schema evolves?).

That can be done :-). Updating the examples would have to be done manually...though they could be tested against the schema and warnings could be issued.

2.  Maybe less obvious.  RELAX-NG lets you "condition" on attributes.  In other words, an element could have two descriptions, with different possible attributes (and their values?), and accordingly have different collections of children.  (I think.)

Yes. I currently follow a dumbed down version of the RELAX-NG algorithm to produce a simplified output. Currently several "versions" of each element are produced and you can manually specify which "version" you want the attributes or parents printed for. I think there's a balance to be struck between the information that an author would find useful and the true rules of the schema. BUT, the full algorithm could be implemented.

I personally hope we can shift towards "one element one rule" usage. It's pretty confusing for an author when they use the same tag in multiple places, but, for example, in one place they can have math and another place they can't. It also happens to make alternative PreTeXt implementations more difficult.

[Jason Siefken]

On 7/12/24 6:20 PM, Joseph DiMuro wrote:

Your timing on this announcement may not have been so good, Jason. A lot of us have our minds on the small documents workshop right now, including myself. :-) Your work looks great, and I think that something like this could be very helpful. But that's all I want to say right now; I don't want to ponder this one any further until after the workshop. :-)

I hope it will be the perfect timing. Documentation is one of the topics that the workshop will feature :-)

[Andrew Scholer]

Cool idea Jason! That looks like it has the potential to be a great resource. Having the schema and examples in one place makes it a lot easier to double-check "how do I say that?" and discover smaller tricks you didn't realize were possible. 

Andrew Scholer (he/him/his)

Computer Science Instructor/Program Chair

Chemeketa Community College

503.589.7649 

computerscience.chemeketa.edu/people/andrew-scholer/

--
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 on the web visit https://groups.google.com/d/msgid/pretext-dev/5e3ea5dd-3ff6-4e38-926a-e155030bf702%40gmail.com.