advice on nesting elements

25 views
Skip to first unread message

Randall Pruim

unread,
Aug 23, 2023, 3:08:37 PM8/23/23
to PreTeXt support

Is there a best practice about what should/should not be nested?  Some examples:

Should definitions/theorems/etc be nexted inside paragraphs, or be siblings of surrounding paragraphs?  Does the flow of the text matter?

What about things like <sage>? <me>?

Really, my question is quite general -- how do I decide what things to nest and what difference will it make for the final product?

The one thing that occurs to me as a consideration is knowls. For example, the scope of an index item could depend on how things are nested (and where the <idx> occurs).

Are there other considerations?  Any advice?

Alex Jordan

unread,
Aug 23, 2023, 3:34:18 PM8/23/23
to pretext...@googlegroups.com
There is a schema that defines what elements are legal children of
what other elements. For example, a "definition" cannot be a child of
a "p", but it can be a child of a "paragraphs". You can browse the
schema here:
https://pretextbook.org/doc/schema/
For example, click on "p (defined in Paragraph group)" to see what is
legal inside a "p" element, as well as what a "p" is legal within.

Also there is a validator that can report to you where you have schema
violations. Setting this up varies from system to system, and some
guidance is here:
https://pretextbook.org/doc/guide/html/jing-trang.html

This still leaves room for "best practice" decisions about many
things, including where to put "idx" elements in many cases. But for
starters you want to have your source valid against the schema.
> --
> You received this message because you are subscribed to the Google Groups "PreTeXt support" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to pretext-suppo...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/pretext-support/e3d1ad77-ac50-4144-a396-87cf550ef2cdn%40googlegroups.com.

Randall Pruim

unread,
Aug 25, 2023, 9:24:11 AM8/25/23
to PreTeXt support

Thanks.

In the guide I see "Reports of other similarly easy installations for other operating systems, to be included here, are especially welcome."  So here is a log of what I did on my Mac.

I installed jing using brew. (Long install with brew, and quite a bit of chatter, but it seems to be working.)  

The instructions in the guide could be improved to make it clear what role aota.xml has in this command:

    jing /path/to/pretext.rng aota.xml.

I first tried using my highest level ptx file.  Doing that gave me several

    error: element "xi:include" not allowed anywhere;

So I'm assuming this doesn't follow includes.  If I run it on one of the lowest level ptx files, then I get a report that seems to flag various improper things, mostly of the form

   element "some element" not allowed here.

So I probably have a bunch of things to fix.  I see jing works with multiple files, so to do the entire book, I can use

   jing /path/to/pretext.rng src/*.ptx

Randall Pruim

unread,
Aug 25, 2023, 9:26:07 AM8/25/23
to PreTeXt support
Also wondering if you have any thoughts on "where to put <idx>" since that comes up fairly frequently.  I seem to recall some advice about not placing <idx> at the very beginning or end of a <p>, which would seem the natural place for a reference to a paragraph.  That's the main guideline I've been following.

Alex Jordan

unread,
Aug 25, 2023, 12:28:47 PM8/25/23
to pretext...@googlegroups.com
This is what I execute to run validation:

java -classpath ~/jing-trang/build
-Dorg.apache.xerces.xni.parser.XMLParserConfiguration=org.apache.xerces.parsers.XIncludeParserConfiguration
-jar ~/jing-trang/build/jing.jar ~/pretext/schema/pretext.rng
$(MAINFILE) > jingreport.txt

where $(MAINFILE) is the project's main ptx file, perhaps with path.
Then I take my time with jingreport.txt and occasionally regenerate
it.

Does something like this work for you and honor inclusion?
> To view this discussion on the web visit https://groups.google.com/d/msgid/pretext-support/e991e122-c5b8-448f-9f64-b5a1c6ed6c15n%40googlegroups.com.

Alex Jordan

unread,
Aug 25, 2023, 12:29:39 PM8/25/23
to pretext...@googlegroups.com
Sorry that's a one-line command that Gmail broke over several lines.

Randall Pruim

unread,
Aug 30, 2023, 12:23:30 AM8/30/23
to PreTeXt support
Regarding jing: This seems to be working for me

    jing ~/projects/github/pretext/schema/pretext.rng src/section1-2.ptx       

I've gone through my book and cleaned up almost everything.  jing does complain about a few things that seem to be working but aren't in the schema, mostly interactive stuff that I inherited.   
Reply all
Reply to author
Forward
0 new messages