improve warnings

[kcrisman]

Here is a typical warning:

MBX:WARNING: unresolved <xref> due to unknown reference "remark-Minkowski"
             located within: "fact-lagrange-four-square" (xml:id), "Lagrange's four square theorem" (title)

This would be more helpful if it said which file this happened in. If this is not possible due to xinclude only being part of the command but the whole xml source is in memory as one "file", maybe the warning could give a few more layers of which section/chapter it is in, at least.

[rbeezer]

xsltproc sees the XML document as one monolithic tree in memory. The files it came from are not known.

The location-report template gives the closest enclosing title and/or author-supplied @xml:id. The idea is you grep or global-find in your editor and you get very close (and know which file!). The alternative is to give title and @xml:id all the way up the tree, which I think is overkill and useless.

Thoughts?

[mitchkeller]

That warning is much nicer than what I remember getting three years ago. You have three strings to grep or global-find for. I don't think there's a better alternative since xsltproc doesn't know the containing file.

[kcrisman]

xsltproc sees the XML document as one monolithic tree in memory. The files it came from are not known.

Hmm, I figured as much.

The location-report template gives the closest enclosing title and/or author-supplied @xml:id. The idea is you grep or global-find in your editor and you get very close (and know which file!).
Unfortunately there are two issues with this:

• Not everyone will know how to do that.
• There may be neither title nor author-supplied id.

You could say those are both user error, but realistically that will not be the case, especially with newer projects.

The alternative is to give title and @xml:id all the way up the tree, which I think is overkill and useless.
Thoughts?

Could there be a fairly well-documented switch or stringparam to the script - maybe -v - that would give very verbose output like that? "PTX Warnings: If you find the warnings overly cryptic (like LaTeX error messages), then once you have fixed the ones you can find, try adding this to your command ..."

I can just imagine these becoming very frustrating if someone has quite a few and isn't very experienced with editors, as opposed to word processing programs. Which is what we hope to be the case, n'est pas?

[davidfarmer]

The documentation cold spell out how to deal with wrnings. It may not be obvious to new people to grep for a string, for example.

…

On Thu, 20 Jun 2019, Mitchel T. Keller wrote: That warning is much nicer than what I remember getting three years ago. You have three strings to grep or global-find for. I don't think there's a better alternative since xsltproc doesn't know the containing file. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute thethread.[AABTULEE2U5MM7OJPZF7523P3R2RHA5CNFSM4HZMKG3KYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWS ZGODYHTE2Q.gif]

[mitchkeller]

I concur with @davidfarmer. For authors using something like Sublime, it's easy to search all of their project's files from within Sublime, but we should tell them that. We should also document how to use grep for a couple of things: dealing with warnings and errors as well as dealing with the output from validation. (Active Calculus gets a lot of permid validation issues now because the schema needs to be updated in places. grep -v is my jam for dealing with that sort of thing, since I only want to see the things that aren't related to permid.) I suggest the Processing, Tools and Workflow chapter of the Author's Guide, but I think there are other equally reasonable locations.

[rbeezer]

This will all be worthwhile to add on the more general #1101