Makefile target names for PDF are confusing

TEIC / TEI

The Text Encoding Initiative Guidelines

https://www.tei-c.org

Other

271 stars 88 forks source link

Makefile target names for PDF are confusing #2217

Closed sydb closed 2 years ago

sydb commented 2 years ago

The Makefile has 3 targets for PDF: Guidelines-pdf:, pdf-complete:, and pdf:. When I inadvertently use the wrong one, you can chalk it up to my being a PDF-generation novice. But @martindholmes just made the same mistake, too, and he is well versed in this stuff. So I claim the names are misleading, and plan to change them:

pdf: That which a user should use to build the PDF version of the Guidelines — stays the same
Guielines-pdf: That which runs the first part of building the PDF version, running the pdfonce target in the antbuilder.xml file (after running check.stamp, p5.xml, and checking Utilities/guidelines-latex.xsl) — rename to pdf-init
pdf-complete: That which runs the final part of building the PDF version, running the pdfrest target in the antbuilder.xml file (why doesn’t it run Guidelines-pdf: first, anyway?) — rename to pdf-finish

peterstadler commented 2 years ago

The idea of improving those targets sounds good to me. As always, naming issues are the hardest! While I intuitively (seem to) understand pdf-init in the sense that it's some (pre)processing step and not finished yet, I find it hard to distinguish pdf and pdf-finish. Is the former more "finished" than the latter? Perhaps it might be better to simply enumerate like pdf-step-1, pdf-step-2, pdf-step-3 and have an alias pdf for the last one?

sydb commented 2 years ago

Good point. I think step names pdf-step-1 and pdf-step-2 are fine, perhaps even better. (The only slight drawback is you have to go look to see if there is a step 3 or not; but if it is less confusing, that is a small price to pay IMHO.)

How about just pdf-initial-step and pdf-final-step (names to deliberately map to the descriptions of @part :-)?

The pdf step would be an alias for pdf-step-1 followed by pdf-step-2, unless we actually want to change how the Makefile executes stuff, which I do not mind, but had not planned.

peterstadler commented 2 years ago

Ok, so do we really need to keep the second step (on its own, without calling the first run first)? That might have some benefit for debugging, but in general you always need the first step before running the second. And since we are renaming things, dependent software (if any) will need to be updated anyway. Hence we could go for only pdf-init and pdf (with a dependency on pdf-init) or am I missing something?

sydb commented 2 years ago

Note: PR 2230 implements @peterstadler’s idea.