IronPort-PHdr: A9a23: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
               gbLOg==
IronPort-HdrOrdr: A9a23:6JppWazmCVRFYKjf1/s6KrPwkr1zdoIgy1knxilNYDZSddGVkN
                  3roeQD2XbP+VEscVwphNzoAtj4fVry7phwiLNhWIuKeCnDlC+WIJp57Y3kqgeQfxHW0uJGz6
                  9vf+xfBbTLfD5HpP336gW5DNosqePvmMvH5Nv29WtnTg1hdshbnmREIzuce3cXeCB2QaMZLd
                  67/cpIpz2pZHQRYICADGIERvWrnayoqLvWJSQeDxpiwgiDhzGl8/rEHwOD3hEYOgkk/Z4StV
                  Ldmwi8w6m9v/TT8HLh/l6W1Y1fnJ/a19NfGNbksKcoAwSpsB+hYMBdW7mP1QpYnN2S
References: <20210420080026.GA823@polynum.com>
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:78.0)
            Gecko/20100101 Thunderbird/78.9.1
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Language: en-GB
Content-Transfer-Encoding: 7bit
Message-ID:  <0127509d-02b8-daa7-a49f-6bf459e75cd7@morningstar2.co.uk>
Date:         Tue, 20 Apr 2021 11:36:57 +0100
Reply-To:     Mailing list for the LaTeX3 project
              <LATEX-L@LISTSERV.UNI-HEIDELBERG.DE>
Sender:       Mailing list for the LaTeX3 project <LATEX-L@LISTSERV.UNI-HEIDELBERG.DE>
From:         Joseph Wright <joseph.wright@MORNINGSTAR2.CO.UK>
Subject: Re: LaTeX required primitives: some questions
To:           LATEX-L@LISTSERV.UNI-HEIDELBERG.DE
In-Reply-To:  <20210420080026.GA823@polynum.com>
Precedence: list
Envelope-To: <rainer.schoepf@gmx.net>
Status: R

Hello,

> I have started to look at the implementation of the LaTeX required
> primitives supplementary to TeX + e-TeX ones and I have some questions.
> 
> Note: I work with the definitions found in the pdfTeX manual and will
> not look at the code since it is GPL'ed one and I don't want someone
> later to claim that my code shall be released under GPL because my eyes
> have touched GPL code.

If you want to avoid the source of pdfTeX, you are likely best starting 
with descriptions of the 'cross engine' primitives that have been 
implemented by other engines.

I would start with:

- l3names. This makes copies of all primitives from all engines 
supported by expl3 into a single namespace. What's important here is 
that we've worked hard to identify which \pdf... primitives are actually 
PDF-related. Only those that relate to PDFs rtain the 'pdf' part of the 
name (*). See lines 605 onward of the current file 
(https://github.com/latex3/latex3/blob/5b6e6f30397930ba96a2b6744171263b370504d5/l3kernel/l3names.dtx#L605)

(*) The 'version' primitives \pdftexbanner, \pdftexrevision and 
\pdftexversion  retain 'pdftex' in their names when saved.

- The XeTeX manual. As XeTeX doesn't directly product PDF output,
   any primitives it provides are not PDF-specific, naming
   notwithstanding. (Newer additions to XeTeX omit the \pdf..., older
   ones do not)

- The e-pTeX setup in 
https://www.tug.org/svn/texlive/trunk/Build/source/texk/web2c/eptexdir/pdfutils.ch?view=log, 
which provides the 'utility' primitive. (There is code in this file, but 
the first ~30 lines are purely descriptive)

> PDF only primitives that I will not implement (correct?):
> 
> \pdfpageheight
> \pdfpagewidth

These work (no error) in DVI mode with pdfTeX, but more importantly in 
XeTeX write information of xdvipdfmx to the XDV file. I would suggest 
having them at least as no-ops.

> Primitives that seem highly linked to PDF and that, to be implemented,
> would need to draw in not ISO C routines but POSIX or MS specific
> because they are linked to filesystems:
> 
> \pdfcreationdate

This one is linked to the PDF, but not the file system: it's what is 
written to the PDF for /CreationDate.

> \pdffilemoddate

This extracts data about a general file from the file system: it's not 
linked to PDF at all. It might be used for example to check on an image 
or data file.

> Primitives that seem highly linked to PDF but that can be implemented
> using ISO C routines:
> 
> \pdffiledump
> \pdfmdfivesum
> \pdffilesize ? (size can be more than integer accepted by TeX)

Again, these are not linked to PDF at all: they all work in DVI mode. 
You could look at the Lua implementation of these used by expl3 - that 
avoids any GPL code. (We want the same *output* as pdfTeX gives, not the 
same implementation.)

I don't think I've ever seen a test of what happens if \pdffilesize is 
used on a truly massive file.

> Primitives whose output seem unclear:
> 
> \pdfnormaldeviate
> \pdfuniformdeviate
> 
> said to generate "an integer" and, afterwards said to expand "to a list
> of tokens". Do they provide, on each call, one integer with the defined
> property or a series of a defined cardinal of such integers or an
> infinite series of such integers until interrupted?

Each use gives one integer. For example, if I do

     \pdfsetrandomseed 1234
     \message{
       \pdfuniformdeviate 1000\space\space
       \pdfuniformdeviate 1000\space\space
       \pdfuniformdeviate 1000\space\space
       \pdfnormaldeviate \space
       \pdfnormaldeviate \space
       \pdfnormaldeviate \space
     }

I get "555 3 641 34071 -99169 33759".

Note that the code for the RNG here comes from MetaPost, and was lightly 
modified to put it into pdfTeX. *Exactly* the same implementation is 
used by XeTeX, pTeX, upTeX and LuaTeX, means that with the same random 
seed the same series of values is obtained independent of the engine 
used. I would strongly urge you to look at the original MetaPost code (I 
believe not GPL).

> The pdf prefix exists because the primitives were added to TeX in pdfTeX
> but it is unfortunate because it seems to link the primitives to the
> PDF format. I'd like to implement them without the pdf prefix and
> provide simply a file for compatibility with \let statements. Would it
> be OK?

As noted, XeTeX has adopted a 'no \pdf...' approach for newer stuff, 
e.g. \strcmp rather than \pdfstrcmp. That works fine provided the names 
are not too generic.

> \engine: a read-only ASCII token identifying the engine: ex.: e-TeX;

This is a very generic name. Moreover, the established pattern is that 
engine define \<name>version and \<name>revision, which can then be used 
as markers for the specific engine. Note that upTeX doesn't do that, and 
that makes identifying that engine more tricky already.

> \apimajor: a positive or nul integer identifying a definite list of
> 	primitives provided;
> 
> \apiminor: a positive or nul integer identifying a definite behavior
> 	(nature, parameters, output, errors) of the primitives;
> 
> \apirevision: a positive or nul integer identifying an implementation
> 	of the (major, minor) combination---the major and minor identify a
> 	contract; the revision identifies a modification of the
> 	implementation of the contract including a correction because the
> 	implementation didn't actually provide the contract. I.e.: bug
> 	fixes, optimizations etc. without any contract modification. The
> 	contract is theoretical.

Again, this just feels like \<engine>version/\<engine>revision: see for 
example how older pdftex.def used to check for available features. 
(Standardisation of engine features over recent years means that this is 
generally not needed.)

> \outfmtlist: a series of ASCII tokens identifying the output format
> 	supported by the engine. Ex.: DVI1.0 (traditional DVI), PDF1.3 etc.
> 	The default format shall be listed first. (Note: I plan, some day,
> 	to extend DVI.)

pdfTeX already defines \pdfoutput, which is 0 for DVI and 1 for PDF. 
LuaTeX renames that to \outputmode but with the same numerical values. 
The version of PDF written by pdfTeX/LuaTeX is set separately using (in 
pdfTeX) \pdfminorversion/\pdfmajorversion, as this is really a separate 
concept to whether PDF or DVI is in use.

There is very little use at the macro level for the DVI level. The PDF 
level does have some impact on output features but in a simply 'Sorry, 
not doable' sense.  Note that XeTeX uses XDV, which is a version of DVI 
dedicated to this engine. It's not necessary to test the DVI version at 
the macro level: what's important is for example which method to include 
imagines, which uses an engine test.

> \outfmtset: setting the output format, that shall be amongst the formats
> 	supported. If not, it returns an error and set the output format to
> 	the default one. Shall be set before \shipout and errors if used
> 	after output has started.
>
> \outfmt: a token identifying the current output format.

See above: data in the same format as other engines is strongly preferred.

I notice you don't mention a large number of the other utility 
primitives. A full list of those assumed by LaTeX in an engine-neutral 
sense is listed in 
https://www.latex-project.org/news/latex2e-news/ltnews31.pdf. See in 
particular that \pdfpage(height|width) are included.

Joseph