New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Initialize branch TagsNTitles; replaces attributes @refnum,@frefnum,@… #966

Merged
merged 6 commits into from Apr 7, 2018

Conversation

Projects
None yet
2 participants
@brucemiller
Owner

brucemiller commented Mar 26, 2018

…rrefnum with more flexible ltx:tags containing multiple ltx:tag, each with @ROLE to indicate what each tag is used for; this allows formatting within the reference numbers, extensibility for new types of tags (eg. hyperref's autoref), possibilities for consolodating duplicated code and making it easier to implement endnotes, glossaries, etc. These changes will be disruptive of some bindings; More to come!

Initialize branch TagsNTitles; replaces attributes @refnum,@frefnum,@…
…rrefnum with more flexible ltx:tags containing multiple ltx:tag, each with @ROLE to indicate what each tag is used for; this allows formatting within the reference numbers, extensibility for new types of tags (eg. hyperref's autoref), possibilities for consolodating duplicated code and making it easier to implement endnotes, glossaries, etc. These changes will be disruptive of some bindings; More to come!
title => orNull($doc->findnode('ltx:bibtag[@role="title"]', $node)),
keytag => orNull($doc->findnode('ltx:bibtag[@role="key"]', $node)),
typetag => orNull($doc->findnode('ltx:bibtag[@role="bibtype"]', $node))); }
authors => orNull($doc->findnode('ltx:tags/ltx:tag[@role="authors"]', $node)),

This comment has been minimized.

@dginev

dginev Mar 26, 2018

Collaborator

Since ltx:tags is used for more than bibliographies, isn't the new selector potentially more general than simply over bibliography tag elements? And is that intended?

This comment has been minimized.

@brucemiller

brucemiller Mar 26, 2018

Owner

Indeed; I replaced sequences of ltx:bibtag by an ltx:tags containing any number of ltx:tag. But ltx:tags is also used to collect the single ltx:tag that were previously allowed at the beginnings of various sectional, floats, theorems, etc (there can now also be multiple ltx:tag). And they're also allowed in equations and such. So, yeah, that was the idea that a collection of tags would become fully general.

This comment has been minimized.

@dginev

dginev Mar 26, 2018

Collaborator

Cool!

<XMath>
<XMApp>
<XMTok fontsize="80%" meaning="not-equals" name="not-=" role="RELOP">≠</XMTok>
<XMTok font="italic" fontsize="80%" role="UNKNOWN">r</XMTok>
<XMTok fontsize="80%" meaning="0" role="NUMBER">0</XMTok>

This comment has been minimized.

@dginev

dginev Mar 26, 2018

Collaborator

unsure if this is minor, but the fontsize attribute disappeared from the individual math tokens? Seems unrelated as a change.

This comment has been minimized.

@brucemiller

brucemiller Mar 26, 2018

Owner

I think this was due to a bugfix that came about as a side-effect of treating tags more uniformly: sometimes the formatter for a tag was something like \bf\thesomething; Hopefully the current code is more consistent about wrapping a group around so that the sideeffects don't leak out, like the small font did here.

<tags>
<tag>1</tag>
<tag role="refnum">1</tag>
<tag role="typerefnum">§1</tag>

This comment has been minimized.

@dginev

dginev Mar 26, 2018

Collaborator

why not trefnum for a role, given there is frefnum? I am unsure if it's better to argue for a single letter convention, or longer attribute names such as refnum_formatted and refnum_type or some such.

Also curious to observe that they really have the same refnum role, but hold distinct variants for that role. Though I suspect adding another attribute is overhead that's not worth its time right now.

This comment has been minimized.

@brucemiller

brucemiller Mar 26, 2018

Owner

I spent a lot of time, and back-and-forth, with the names, trying to improve over "frefnum" :> There are 3 base cases roughly equivalent to the former frefnum, refnum and rrefnum, but hopefully with more explanatory names, but perhaps those names can be further clarified.

  • No role is a "formatted refnum"; it is used for the display in or alongside the object being tagged (eg. items, equations) Exception is that objects with a title or caption, the tag is essentially duplicated within the title/caption so the one in the ltx:tags is likely never used.
  • @role=refnum is the plain refnum, essentially \thecounter which LaTeX would use to fill in \ref. Note that the author typically gives some context like see section \ref{foo}, and that not all objects get a refnum, in which case latex uses the refnum of the parent.
  • @role=typerefnum is a "typed refnum" for use when generating references to an object, typically automated, such as back-references and such. There's no context there, so the type name or symbol is helpful.

Hope that helps; if you can think of better names...

This comment has been minimized.

@dginev

dginev Mar 26, 2018

Collaborator

Thanks! Got it.

Well, refnum_formatted and refnum_typed do sound better to me, but they are also long, so probably not ideal. I still slightly lean towards recommending them...

This comment has been minimized.

@dginev

dginev Mar 26, 2018

Collaborator

The other, more informal-sounding, bunch of names that come to mind are things like fmtnum and typnum, but I don't really find the appeal in such dashing shorthands nowadays.

<table frefnum="Table 1" refnum="1" xml:id="S0.T1">
<table xml:id="S0.T1">
<tags>
<tag>Table 1</tag>

This comment has been minimized.

@dginev

dginev Mar 26, 2018

Collaborator

just as a readability remark, I'm unsure what the tag with no attribute signifies. Looking at the diff I assume it is the frefnum that was originally on the table element? If so, maybe it warrants a role attribute specifying that?

This comment has been minimized.

@brucemiller

brucemiller Mar 26, 2018

Owner

see reply to previous comment about what the lack of @role means. Either can be default or explicit, if there's a meaningful name for it.

@@ -825,6 +882,9 @@ Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
</div>
</div>
<div>
<!-- The element tags
is currently not supported for the main body.
-->

This comment has been minimized.

@dginev

dginev Mar 26, 2018

Collaborator

Extremely minor, but seeing this same comment on every div feels a bit verbose.

This comment has been minimized.

@brucemiller

brucemiller Mar 26, 2018

Owner

Yeah, the original author of the TEI & JATS stylesheets had different approach than I'm used to. Not sure if those messages were intended only for development or not.

@dginev

This comment has been minimized.

Collaborator

dginev commented Mar 26, 2018

For what it's worth, I skimmed the code and left minor comments. The change set is very impressive! So I can not claim any reasonable quality control, but at least I understand the diffs better.

Depositing so many refnum-like tags does feel redundant while skimming, but it's probably worth the trouble given how much machinery requires the different variants. I can definitely believe this makes writing the XSLTs much easier. So all 👍 from me, let me know if you'd like me to take a closer look at some specific bit.

brucemiller added some commits Mar 27, 2018

Record whether objects go into toc, lof, etc, in an attribute @inlist;…
… make ltx:TOC use @lists, rather than @ROLE for corresponding purpose; implement \addcontentsline; otherwise support the various toc and list commands more in tune with the way LaTeX does it, and reduce the dependence on explicit lists of element names
@brucemiller

This comment has been minimized.

Owner

brucemiller commented Apr 7, 2018

OK, let's cross our fingers and do it!

@brucemiller brucemiller merged commit ec5561c into master Apr 7, 2018

2 checks passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
continuous-integration/travis-ci/push The Travis CI build passed
Details

@brucemiller brucemiller deleted the TagsNTitles branch Apr 7, 2018

@dginev

This comment has been minimized.

Collaborator

dginev commented Apr 7, 2018

oh wow, it shipped! 🚀

Time to do some testing...

@dginev

This comment has been minimized.

Collaborator

dginev commented Apr 7, 2018

Also, it just occurred to me that some of the production users of latexml are not on the mailing list - so it may be a great idea to update the Changes file already, so that people know about the big developments early.

The best way to do that may be adding a header line on the top:

0.8.3 [in development]

and bookkeep the changes as PRs get merged, especially major ones. Bonus outcome - releasing the next version becomes as simple as bumping the date in the file, and it's less likely to forget some change set.

Just a thought, since this specific PR changes a lot, and it is quite possible production deployments may hit underwater discrepancies.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment