Makefile target names for PDF are confusing

[sydb]

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]

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]

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]

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]

Note: PR 2230 implements @peterstadler’s idea.