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

Merged
merged 6 commits into from Apr 7, 2018

## Conversation

Projects
None yet
2 participants
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!
 21ab86d 

### dginev reviewed Mar 26, 2018

 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)),

#### 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?

#### 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.

Collaborator

Cool!

### dginev reviewed Mar 26, 2018

 r 0

#### 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.

#### 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.

### dginev reviewed Mar 26, 2018

 1 1 §1

#### dginev Mar 26, 2018 • edited

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.

#### 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...

#### 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...

#### 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.

### dginev reviewed Mar 26, 2018

 Table 1

#### 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?

#### 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.

### dginev reviewed Mar 26, 2018

 @@ -825,6 +882,9 @@ Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor

#### dginev Mar 26, 2018

Collaborator

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

#### 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.

Collaborator

### dginev commented Mar 26, 2018 • edited

 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

 Merge branch 'master' into TagsNTitles 
 0507d6e 
 freshened manual 
 b069c94 
 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
 f7891f9 
 Fixed up plain and added testcase 
 d10ca0e 
 fixed up bibitem and other refnum cleanup 
 77eb1a9 
Owner

### brucemiller commented Apr 7, 2018

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

### brucemiller merged commit ec5561c into master Apr 7, 2018 2 checks passed

#### 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

Collaborator

### dginev commented Apr 7, 2018

 oh wow, it shipped! 🚀 Time to do some testing...
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.