No (Runestone) exercises in an introduction ??

[bnmnetp]

When I try to put a multiple choice question in an introduction it shows up like this:

If I move the code for it to the subsection below the introduction the question renders as expected.

Can we not have exercises in an introduction or is this a bug?

[Alex-Jordan]

At present, an "introduction" is viewed as too minimal to have exercises inside it. Normally I'd advise someone to change their "introduction" to a "subsection" whose title is "Introduction". But maybe Rob will accommodate more for this in Runestone? How do you feel about using a "subsection" instead?

[bnmnetp]

Hmmm, I thought that if you had a subsection you had to have an introduction. I'm still learning the rules. This is in a book that david converted from latex for us, so I don't have any opinions on the way it is structured, and I'm still figuring out the semantics of some things.

In the thinkcspy book I convert I don't have introductions my sections are unstructured (I think that is the term) but will often have a question right away to get students thinking, so it seemed pretty logical to put one in the introduction to me.

[rbeezer]

I'd forgotten about the maintenance task of really clamping down on introduction. Short version: no numbered stuff in an introduction or conclusion. Two options, @Alex-Jordan is suggesting one of them( and so would I).

See https://pretextbook.org/doc/guide/html/overview-structure.html

[Alex-Jordan]

It's the other way around. If you have an "introduction" in your "section" then your "section" is structured, so it should have "subsection(s)". But an "introduction" is optional.

[bnmnetp]

OK, I read that, (even before I filed this) but it doesn't say anything about limiting what is in an introduction.

So I guess my question then is what is the purpose of an introduction and conclusion tag?? Not trying to snark, but I want to understand so that when I get questions on Slack I can say something intelligent.

I'm fine with Alex's suggestion.

[bnmnetp]

Sphinx has a debug setting that causes the error message to appear in the output (html/latex/etc) So that when you look at the page instead of seeing nothing or the kind of random stuff I circled above you would see a message, in red, inside a box, that says "Error on line: XX of YY.rst -- Numbered elements are not allowed in an introduction division"

Maybe automatically running Jaas would spew that out as well. But when your warnings and errors go on for many pages it is easy to miss. That is certainly the case with this converted book. Its hard to see the important stuff in the midst of all of the other important stuff that you have been ignoring for weeks. But when it appears in the book that grabs your attention!

[Alex-Jordan]

what is the purpose of an introduction

I'd say it's just a short textual introduction that loosely ties together the theses of the subsections that follow. Can appear on the chapter's title page, unlike the first subsection which often starts on a fresh page.

Conclusions are a little messier. Output formats can confuse them with the final subsection, or they get sucked up inside the final subsection. Care is needed to prevent that. But the idea is similar: some brief text that ties together the preceding subsections without belonging to any one of them in particular.

[rbeezer]

This is a historical mess, mostly of my making. It was always meant to be just a paragraph or two of text. One symptom, LaTeX will make numbers like 14.0.5 for the fifth theorem of the introduction to Chapter 14. I think that is ugly.

Anyway, permissive XSL let people do lots of bad things. Clamping down will require care, and as a corollary it is not documented. Yet. Sorry for the rough edges. The schema will complain about incorrect structure, but maybe not contents. Yet.

[bnmnetp]

We computer scientists love 14.0.5 🤪

Thanks for the history lesson, and of course you don't need to explain or apologize for historical messes (or lack of docs) to me!!

I am happy to contribute little PR's to the documentation as we encounter things that we do not understand. That is far more productive than making issues.

Its all to easy to assume that the converter was right! In this case, said introduction was way longer than two paragraphs. It seems the latex to PreTeXt conversion scripts package up everything from the start of a section until the first \subsection as an introduction. Maybe that is fine, if you didn't write it with the structure of an introduction in mind then it makes trouble.

[rbeezer]

Right on each and every count. Unclear if the converter should just make a run of unstructured text prior to a subdivision into a like subdivision. It'll bump the numbering of the subdivisions, but then an author should be making a clean break (and can manually fix). One for @davidfarmer to consider.

The place to address this is in the follwing paragraph, or maybe just afterwards. Advice now might just say "keep it simple, s------"

https://pretextbook.org/doc/guide/html/topic-divisions.html#p-345

[bhoffman0]

This issue is broader than the introduction tag. If an exercise is not in a subsection with a title or an exercises section, it does not render. Learning this the hard way through trial and error.

[bnmnetp]

Beryl, there must be something different in what you are doing than what I am doing in various places, because for me it is not the case that exercises have to be in a subsection.

I just removed the subsections from ch-methods-exs.ptx and the exercises all are fine...

What you probably want to do for an entire section of exercises is make the top level tag in that file <exercises ... Again, no need for subsections. Then all of the individual <exercise> are numbered rather than labeled as checkpoints.

[rbeezer]

Perhaps a section begins, has an exercise and later there is a subsection? If a section has any subsection then it must be structured, mostly with subsection. @bhoffman0 - are you validating against the schema? That would indicate these situations (but new markup for Runestone is not there yet).

[bnmnetp]

@rbeezer -- interestingly, in the thinkcspy book this unstructured structure happens in many places. (It is on my list to clean up!) Section containing by a video and maybe a mchoice and a program, and then a subsection. I get many warnings and schema validation complaints due to this. But, <exercise> and <program> still render properly outside of a subsection when I build.

@bhoffman0 I think a fuller example copied in here for Rob to look at would help get to the bottom of this.

[bhoffman0]

I did more testing this morning and you're right that they work outside of a subsection, but we were putting them in other contexts where they do not display like listing and li. I just pushed https://github.com/ram8647/javajavajava/blob/master/pretext/chptr4Methods/demo-not-working-exs.ptx which shows 3 contexts where things don't display. Although you have a lot of examples of using the program tag inside a listing tag in https://github.com/PreTeXtBook/pretext/blob/master/examples/sample-book/rune.xml, whenever we try that, it does not display the program at all. The same thing happens if it's inside ol li tags which was how a lot of the exercises in this converted book were formatted. We also couldn't get interactive=codelens to display although it works in your pretext book example. We'll come to the PreTeXt drop in on Tuesday.

[bnmnetp]

Thanks @bhoffman0. The program in a listing problem does appear to be a regression @rbeezer . When I build the book from the repo the listings render properly. But when I build with pretext-cli (as Beryl is doing) it doesn't work.

[rbeezer]

When I build the book from the repo

Do you mean using the pretext/pretext script? I maintain that and do not even have the CLI installed.

Does the PTX sample book build for Beryl with the CLI? Recognize that the CLI is on a release schedule and lags. The repo gets updates all the time. I'm at a bit of a loss to explain the described behavior.

[bnmnetp]

sorry, yes from the pretext/pretext script, and I understand that the cli is not always in sync with what I pull from github for pretext/pretext.

So it seems there must be some kind of regression that is in the 0.6.4 of the cli but is fixed in pretext/pretext

[rbeezer]

Do "pretext support" with CLI and post the commit hash here. I'll look at a diff and see if any alarm bells go off. Later, off-duty the rest of the afternoon.

On June 12, 2022 11:51:07 AM PDT, Bradley Miller @.***> wrote:

sorry, yes from the pretext/pretext script, and I understand that the cli is not always in sync with what I pull from github for pretext/pretext.

So it seems there must be some kind of regression that is in the 0.6.4 of the cli but is fixed in pretext/pretext

[bnmnetp]

PreTeXt project found in `/Users/bmiller/src/pretext/doc/guide`.

Please share the following information when posting to the
pretext-support Google Group.

PreTeXt-CLI version: 0.6.4
    PyPI link: https://pypi.org/project/pretextbook/0.6.4/
PreTeXt core resources commit: c8cb39bd3890ab4a044792fc5b65a51548494ec7
OS: macOS-12.4-arm64-arm-64bit
Python version: 3.9.12
Current working directory: /Users/bmiller/src/pretext/doc/guide
PreTeXt project path: /Users/bmiller/src/pretext/doc/guide

Contents of project.ptx:
------------------------
<!--
    This file provides the overall configuration for your PreTeXt
    project. To edit the content of your document, open `source/main.ptx`
    (default location).
--><project>
  <targets>
    <target name="html">
      <format>html</format>
      <source>guide.xml</source>
      <publication>publication.xml</publication>
      <output-dir>output/html</output-dir>
    </target>
    <target name="latex">
      <format>latex</format>
      <source>guide.xml</source>
      <output-dir>output/latex</output-dir>
    </target>
    <target name="pdf" pdf-method="pdflatex">
      <format>pdf</format>
      <source>guide.xml</source>
      <output-dir>output/pdf</output-dir>
    </target>
  </targets>
  <executables>
    <latex>latex</latex>
    <pdflatex>pdflatex</pdflatex>
    <xelatex>xelatex</xelatex>
    <pdfsvg>pdf2svg</pdfsvg>
    <asy>asy</asy>
    <sage>sage</sage>
    <pdfpng>convert</pdfpng>
    <pdfeps>pdftops</pdfeps>
    <pdfcrop>pdf-crop-margins</pdfcrop>
    <pageres>pageres</pageres>
    <node>node</node>
    <liblouis>file2brl</liblouis>
  </executables>
</project>

[rbeezer]

Thanks, @bnmnetp, for the commit hash. Lots of looking to see what has changed, and I'm not seeing anything at all even remotely suspicious.

Thanks, @bhoffman0 , for the example source files, that helps a lot.

• listing/program looks good as source. But is a mystery to me why it is failing.
• Java codelens: must be on a Runestone server, or else you should build the necessary trace data with the pretext/pretext script. Look in examples/sample-book/generated/trace/ for examples of what I mean.
• Lists are a popular oganizational tool, which are generally not very effective. So, for example, numbered items (like an exercise) can't go there.

Can I suggest that while all this Runestone integration is happening, we do not use the CLI, or at least test with the pretext/pretext script? It'll be a nightmare to have people building with old code?

https://pretextbook.org/doc/guide/html/pretext-script.html

[rbeezer]

listing/program looks good as source. But is a mystery to me why it is failing.

Resolved during Runestone Drop-In. Publication file was putting listings into knowls, and work remains to have Runestne Components behave inside knowls. @bnmnetp knows what is needed.

Beryl got all three of the suspect situations to behave. I'm still working on CodeLens in an interactive exercise.