[DEPRECATE] Cross-reference text style selection

[Robert Beezer]

Authors,

Changes here are mostly backward-compatible and non-urgent, with one exception that has a huge impact and a simple (urgent) fix.

The per-xref @autoname attribute is deprecated.  But it still works.  You will get warnings.

The command-line stringparam "autoname" is deprecated. But it still works.  You will get warnings.

For per-xref settings, use @text:  "global" is the old @autoname="no", 5.2; "type-global" is the old @autoname="yes", Theorem 5.2; "title" is the old @autoname="title", Smith's Theorem.

Document-wide setting is now part of your source, since the words in your output will change based on the setting you choose.  So now use  docinfo/cross-references/@text  with the same strings as above.  Look for more command-line parameters to go away and be replaced in docinfo by attribute values.

Here is the gotcha.  No command-line parameter and no docinfo/cross-references and the old default was 'no' (= 'global').  I've taken this opportunity to improve the out-of-the-box experience and make the default  'type-global'.  Mature projects will get a warning, minimal projects will not.  Make a  docinfo  setting, even if it matches the new default, to make the warning go away.

Fix:  <cross-references text="global" /> in docinfo will behave like the old default.  If your project is designed around assuming the old default behavior, then this is an urgent change for you, since the new default will behave very differently.  If you are presently setting the global  autoname  switch then you can wait on making changes.

Rob

[twjudson]

What if I want to reference Chapters 1–5?

[Rob Beezer]

<xref @first="chap-intro" @last="chap-hard">Chapters</xref>

(without "Chapters", you automatically get a singular "Chapter" twice, I
believe, Chapter 1-Chapter 5). Set @text to 'type-global' or 'type-local' on
the xref, or document-wide in "docinfo".

Report back if that does not work. Maybe more in the Author's Guide this
morning if I get some code wrapped up.

> --
> You received this message because you are subscribed to the Google Groups
> "MathBook XML Support" group.
> To unsubscribe from this group and stop receiving emails from it, send an email
> to mathbook-xml-sup...@googlegroups.com
> <mailto:mathbook-xml-sup...@googlegroups.com>.
> For more options, visit https://groups.google.com/d/optout.

[Thomas Judson]

I am currently cleaning up the ODE Project.  I haven’t needed to do this yet, I just wondered if you could.  However, I tried

See <xref @first="secondorder" @last="nonlinear">Chapters</xref>

and it blows up.

cd /Users/twjudson1/Desktop/temp/odeproject/html; \

xsltproc --xinclude /Users/twjudson1/Documents/mathbook/user/odeproject-html.xsl /Users/twjudson1/Documents/books/odeproject/src/odeproject.xml

/Users/twjudson1/Documents/books/odeproject/src/firstlook01.xml:298: parser error : error parsing attribute name

rder differential equations more fully in <xref ref="secondorder"/>.  See <xref 

                                                                               ^

/Users/twjudson1/Documents/books/odeproject/src/firstlook01.xml:298: parser error : attributes construct error

rder differential equations more fully in <xref ref="secondorder"/>.  See <xref 

                                                                               ^

/Users/twjudson1/Documents/books/odeproject/src/firstlook01.xml:298: parser error : Couldn't find end of Start Tag xref line 298

rder differential equations more fully in <xref ref="secondorder"/>.  See <xref 

                                                                               ^

/Users/twjudson1/Documents/books/odeproject/src/firstlook01.xml:298: parser error : Opening and ending tag mismatch: p line 298 and xref

econdorder"/>.  See <xref @first="secondorder" @last="nonlinear">Chapters</xref>

                                                                               ^

/Users/twjudson1/Documents/books/odeproject/src/firstlook01.xml:298: parser error : Opening and ending tag mismatch: subsection line 136 and p

ndorder"/>.  See <xref @first="secondorder" @last="nonlinear">Chapters</xref></p

                                                                               ^

/Users/twjudson1/Documents/books/odeproject/src/firstlook01.xml:300: parser error : Opening and ending tag mismatch: section line 9 and subsection

    </subsection>

                 ^

/Users/twjudson1/Documents/books/odeproject/src/firstlook01.xml:302: parser error : Extra content at the end of the document

  <subsection xml:id="subsection-firstlook01-predator-prey">

  ^

/Users/twjudson1/Documents/books/odeproject/src/odeproject.xml:30: element include: XInclude error : could not load /Users/twjudson1/Documents/books/odeproject/src/firstlook01.xml, and no fallback was found

make: *** [html] Error 6

Thomass-MacBook:script twjudson1$ 

You received this message because you are subscribed to a topic in the Google Groups "MathBook XML Support" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/mathbook-xml-support/JgyF_CWdyR0/unsubscribe.
To unsubscribe from this group and all its topics, send an email to mathbook-xml-sup...@googlegroups.com.

[Alex Jordan]

Don't actually put the "@" in the attributes. Rob is bouncing back and forth between XML and XSL too much :)

<xref first="secondorder" last="nonlinear">Chapters</xref>

[Thomas Judson]

That works.  With enough time, I would have figured this out.

On Jul 30, 2017, at 5:53 PM, Alex Jordan <jordanc...@gmail.com> wrote:

Don't actually put the "@" in the attributes. Rob is bouncing back and forth between XML and XSL too much :)

<xref first="secondorder" last="nonlinear">Chapters</xref>

[Rob Beezer]

My bad. Moving too fast between code and documentation.

No "@" on first and last. ;-)

[Rob Beezer]

And should read all his messages before replying to any of them. ;-)

[Thomas Judson]

Regardless, everything works as it should.

> You received this message because you are subscribed to a topic in the Google Groups "MathBook XML Support" group.
> To unsubscribe from this topic, visit https://groups.google.com/d/topic/mathbook-xml-support/JgyF_CWdyR0/unsubscribe.

> To unsubscribe from this group and all its topics, send an email to mathbook-xml-sup...@googlegroups.com.

[Matt Boelkins]

I updated my version of Mathbook this morning and am getting cross-reference errors.  I'm not sure if this is the issue that you are talking about here in this thread on style selection or not.  Also, there's been a lot of recent traffic here on the list, so apologies if I have missed discussion of this somewhere else.

Essentially the section number is being left out of references.  So where it should say "Figure 1.3.2", the text says "Figure 2", and where it should say "Preview Activity 1.3.1", the text says "Preview Activity 1".  See attached screenshot for how it looks to me, as compared to the (not-very-old) HTML will I still have posted at http://faculty.gvsu.edu/boelkinm/Home/AC/sec-1-3-derivative-pt.html which was compiled under Mathbook about 10 days ago.  

This issue with cross-reference numbering happens globally.

By the way, when I hover my mouse over what now says "Figure 2", the little bubble that pops up says "Figure 1.3.2", which is right, and of course clicking on the link actually points to the right item.

Thanks,

Matt

[Rob Beezer]

Dear Matt,

Very observant. Not a bug, that is a feature. ;-)

Without looking, I can guess that your cross-reference to Figure 1.3.2 lies in
Section 1.3.

Find a cross-reference that points "far away" and it will look "right."

1. Yes, in all the traffic you missed a follow-on announcement. We are working
on it (the traffic).

2. Are you not getting a warning about the default? Could it be improved?

3. Stop using "autoname" at the command-line and instead inside "docinfo" add

<cross-references text="type-global" />

to go back to the way I think you were.

4. Much more at:
http://mathbook.pugetsound.edu/doc/author-guide/html/topic-cross-referencing.html

I hope MathFest went well!

Rob

[Matt Boelkins]

Rob,

I see and understand the rationale.  Most of my cross-references are local and nearby.  But I personally find it unusual to see a caption that says "Figure 1.2.3" and then a nearby sentence that refers to that figure as "Figure 3."

> 2.  Are you not getting a warning about the default?  Could it be improved?

I think the only warning I'm getting is the following, which seems to be about something else:

"MBX:DEPRECATE: (2017-07-25) the default version of text for cross-references has changed.  Rather than simply numbers, they will be prefixed by type-names as well.  So you could see duplicates like "Theorem Theorem 5.2".  Set  "docinfo/cross-references/@text"  to  "global"  to restore old behavior."

> 3. Stop using "autoname" at the command-line and instead inside "docinfo" add  <cross-references text="type-global" />

OK, I will use that to revert, at least for now.  I appreciate having the option to go both ways with it.

Matt

to mathbook-xml-support+unsubscrib...@googlegroups.com
<mailto:mathbook-xml-support+unsubs...@googlegroups.com>.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to a topic in the Google Groups "MathBook XML Support" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/mathbook-xml-support/JgyF_CWdyR0/unsubscribe.
To unsubscribe from this group and all its topics, send an email to mathbook-xml-support+unsubscrib...@googlegroups.com.

[Rob Beezer]

On 08/01/2017 03:51 PM, Matt Boelkins wrote:
> I see and understand the rationale. Most of my cross-references are local and
> nearby. But I personally find it unusual to see a caption that says "Figure
> 1.2.3" and then a nearby sentence that refers to that figure as "Figure 3."

I find it pretty amazing. But then, I'm a graph theorist. (Which does not seem
to be appreciated around here! ;-) ).

"Local" references were requested for things like exercises. So I just did it
for everything. Then made it the default, so authors know they can use it.

>> 2. Are you not getting a warning about the default? Could it be improved?
>
> I think the only warning I'm getting is the following, which seems to be about
> something else:
>
> "MBX:DEPRECATE: (2017-07-25) the default version of text for cross-references
> has changed. Rather than simply numbers, they will be prefixed by type-names as
> well. So you could see duplicates like "Theorem Theorem 5.2". Set
> "docinfo/cross-references/@text" to "global" to restore old behavior."

The first sentence is accurate. Default changed twice in a week. ;-)

>> 3. Stop using "autoname" at the command-line and instead inside "docinfo"
> add <cross-references text="type-global" />
>
> OK, I will use that to revert, at least for now. I appreciate having the option
> to go both ways with it.

Fine. Don't switch over into graph theory. ;-) Thanks for the report from the
front.

Rob

[David Farmer]

I think Matt makes a pretty strong case to have different defaults
for different types of object.

Just like a Theorem is born with the name 5.2.3 and
and exercise is born with the name 3 (or maybe c),
(You have to "look up" to see that the exercise has an ancestor
with name 5.3) the way it is referred to locally should
maybe be use the name it is born with?

> --
> You received this message because you are subscribed to the Google Groups
> "MathBook XML Support" group.
> To unsubscribe from this group and stop receiving emails from it, send an

> email to mathbook-xml-sup...@googlegroups.com.

[Rob Beezer]

The authors of developmental math books made a case for (a) long numbers
intimidating their students, and (b) most of their references being short-distance.

@text="born" would be a reasonable tenth scheme. But after a solid week working
on cross-references, with a few loose ends still left dangling, I'm unlikely to
start a new scheme until I take care of other major projects.

One of the things I have tried to do is (i) make defaults sensible for a good
out-of-the-box experience, (ii) choose defaults that expose features authors may
not know about, with an easy way to switch to something else (knowled examples
being the canonical example).

If there is a consensus (more than two replies) that I have the balance of (i)
and (ii) wrong here, we can change the default again easily.

Folks should set docinfo/cross-references/@text to what they really want,
after reading the relevant section of Chapter 6 of the Author's Guide.

Rob

[Bruce Yoshiwara]

Like Matt, I'd like the caption on the figure and the cross-reference to match. But I'd like them to match by both of them being short, "Figure 3" in both places. Similarly for Examples, in-line Exercises, and Tables (and Theorems if I used them). Can they be "born with" a simple number and look up to see ancester N.M?

In Kathy's book (and many other developmental math textbooks), the first example in Chapter N, Section M is called simply Example 1, not Example N.M.1. I know that I can now get a cross-reference to be something like "Example 1" rather than "Example N.M.1" by using text="type-local", but can I get that same short name for the actual Example? That is, can I display Examples, Figures, Exercises, and Tables with just a short number (even though PreTeXt is keeping track of the chapter and section levels)?

(And when the example is far away, the cross-reference phrase would show something like "Example 3 of Section M in Chapter N" or "Example 3 of Section N.M")

Bruce

> email to mathbook-xml-support+unsub...@googlegroups.com.

[Bruce Yoshiwara]

Oh, and it would also be nice if the Examples, Figures, Tables, and Exercises were numbered independently. So, for instance, the example after Example 1 would be Example 2, even if there were Figures, Tables, and Exercises in between.

Bruce