Table numbering is inconsistent

[mhagander]

There appears to be no sync between table numbering in the slide book and in the handouts.

For example, I have a set built off 6691715. In section 7.7, the VCL built-in subroutines table is numbered 15 in the handouts but 12 in the slides. Same error for table 16 vs 13 etc.

This is really confusing when trying to reference one or the other in discussions with the students. The same table should obviously have the same number in both cases. (It might change in different releases of the documentation of course, but should be consistent within one)

[franciscovg]

I see the problem. Numbering is different because of the way that the source code for the slides is created. Makefile removes the hangouts and creates the slides from the rest. That process removes some tables and therefore different numbering.

A quick fix is to remove the numbers from the slides, or do you have another suggestion?

[dridi]

We could give short-names instead of numbers, they are more likely to stay consistent over time.

[mhagander]

Having table numbering is certainly very useful, to reference between the two documents. I don't know the toolchain enough to say if there's a way to do that automatically though. But given how fairly seldom they change, perhaps it would work to use hard-coded numbering (with a check somewhere that would make sure there are no accidental duplicates). That would be similar to the suggestion from @dridi, but still using numbers rather than names..

Might that be doable?

[dridi]

At this point it might be worth considering switching to another markup technology, with more capabilities. The book vs slides rendering brings many issues as the book increases in complexity, and this suggestion is yet another complexity bump.

I'm not suggesting short-names because I don't like @franciscovg's figure numbering or @mhagander's attempt to prevent numbers from diverging over time. It's just getting too complex in my opinion and maybe rst isn't good enough for that.

Another 'nother option could be to write an rst extension in python in order to take care of the book/slides specifics and keep complexity under control, but then I'm worried about portability issues (which may in turn increase complexity).

[franciscovg]

I agree with you two, @mhagander and @dridi. We'd need to investigate and compare relevant alternatives. Personally I like LaTeX and it has been a while I have thought about trying DocBook. Do you have any suggestion about another markup language we should consider to evaluate?

[dridi]

My main issue with LaTeX is the lack of actual portability, especially with themes, and we need something also relevant for the html export. My opinion on DocBook is NOOOO 🙅

I don't know (yet?) any other markup/tooling that we can use to easily output:

• PDF slides
• PDF book
• HTML book

[gquintard]

Isn't the problem more generic than the tech used?

I mean, if you have three figures and the book has two and the slides have two, how do you number them?

[dridi]

@gquintard it's more like if you have three figures in a chapter, the book will show the three of them but the slides may show less. And the slides may not show the N first so we can number them "chapter.figure_n" and expect consistency.

[mhagander]

To me, that one is pretty clear. You number them based on which edition has the most (the book), and just skip some in the slides.

It would be troublesome if there were some figures in the book but not in the slides and some in the slides but not in the book. But that's not the case here -- there are none in the slides that are not also in the book.

[gquintard]

Ah, thanks for clarifying

[franciscovg]

@dridi, I'm not sure what do you mean with portability issues of LaTeX, since it is available on most operating systems. DocBook can output HTML, so that's not an argument for an immediate strong rejection.

One solution for the numbering problem is to have the documentation tool create the slides from a cropped version of the output, not the source. I don't know whether this is a ready-to-use option in some of the available tools out there.

[dridi]

@franciscovg I have tried in the past to get a build system for LaTeX documents that would work on different platforms, and there were too many variations between different tex distributions.

Regarding docbook, I never commented on its capabilities, I don't want it because of its syntax.

One solution for the numbering problem is to have the documentation tool create the slides from a cropped version of the output, not the source.

More complexity. At least with named figures with can use links, so only physical books wouldn't make it easy to follow references.