Executable schema

[oscarlevin]

Inside <executables>, have tags for each executable, that can have attributes @path, @server, and @method (which could be "server" or "local".

[StevenClontz]

Should @path be @local to match the choices for @method?

[bjones1]

I'm looking for ways to make this as simple as possible for our users. My thoughts:

• We don't need local/server support for most of our executables; AFAIK, we only support asymptote and sage as a server.
• Attributes on the <executables> tag are simple and cover 99% of our use cases.
• For users who have an old sage/asymptote installed locally but want to use the server instead, provide a <asy method="local or server"> tag.
• We don't need to support specifying both a local path and a server path, since only one can be in use for a build.

My proposal:

<?xml version="1.0" encoding="utf-8"?>
<executables
  latex="/local/path/to/latex" 
  pdflatex="/local/path/to/pdflatex"
  ... etc.

  asy="/local/path/to/asy or https://address/of/asy.org"
  sage="/local/path/to/sage or https://address/of/sage.org"
>
  <asy method="local or global"/>
  <sage method="local or server"/>
</executables>

Rules:

• For everything but asy and sage (and perhaps jing), all paths are local, with sensible defaults of these aren't present.
• If the asy="..." or sage="..." attributes exist, but <asy method="..."/> / <sage method="..."/> tags don't exist, infer the method from the provided attribute: a prefix of http(s):// means server, otherwise it's a local path.
• If only the <asy method="..."/> / <sage method="..."/> tags exist, but the asy="..." or sage="..." attributes don't exist, then use the method to choose a sensible default (local path vs. server address).

[bjones1]

Future thoughts:

• Would we ever support a local install of jing for validation? That's probably easy to do with our Codespace setup. I'm a big fan of validation.
• Would we ever support a local install of webwork?

[StevenClontz]

AFAIK, we only support asymptote and sage as a server.

Core PreTeXt has support for these local non-Python dependencies (and we should too, even if we have a server alternative): https://github.com/PreTeXtBook/pretext/blob/master/pretext/pretext.cfg#L55

[bjones1]

I mean, asymptote and sage can be run either locally or on a sever; the rest of these are local-only executables.

[StevenClontz]

local install of webwork?

@Alex-Jordan is this an option these days?

[StevenClontz]

@bjones1 Let me think about it, but I think I prefer

<executables>
   <foo path="bar" method="server"/>
   <baz path="wee"/>
</executables>

over

<executables
    foo="bar" 
    baz="wee"/>
    <foo method="server"/>
</executables>

[rbeezer]

Elements are expensive. You will be happier with one element used repeatedly with an attribute for the program/purpose.

…

On July 26, 2023 7:50:48 PM GMT+02:00, Steven Clontz ***@***.***> wrote: @bjones1 Let me think about it, but I think I prefer ```xml <executables> <foo path="bar" method="server"/> <baz path="wee"/> </executables> ``` over ```xml <executables foo="bar" baz="wee"/> <foo method="server"/> </executables> ```

[bjones1]

How about:

<?xml version="1.0" encoding="utf-8"?>
<executables>
  <!-- The `method` attribute is optional in the following tags. If present, 
        it must be "local" for everything but sage and asymptote. 
       
       The content of the tag is required; it is always a local filesystem 
       path to the relevant executable. -->
  <executable name="latex" method="local">/local/path/to/latex</executable>
  <!-- For example, the method is not included here. (There's no point to 
       include it when there's only one option.) -->
  <executable name="pdflatex">/local/path/to/pdflatex</executable>
  <!-- Same for xelatex, pdfsvg, pdfpng, pdfeps, node, liblouis. -->

  <!-- The method is optional in the following tags. If present, it may be 
    "local" or "server". If absent, then:
    - If the tag has content, then infer the method based on the
     presence or absence of the `http(s)://` tag.
    - If the tag lacks content, try a local call of `asy`; if that fails, 
      contact the default asymptote server.
       
    The contents of the tag are optional; they are either:
    - A local filesystem path to the relevant executable OR
    - A URL to a server; the URL must start with "http(s)://". -->
  <executable name="asy" method="server"/>
  <executable name="sage">https://address/of/sage.org</executable>
</executables>

[oscarlevin]

The publisher specifies which webwork server to use (i.e., it's in the publication file). Perhaps if you wanted to force a particular server that you know has compatibility with your code, you should specify that in a persistent way, not in the non-tracked executables file.

So maybe that makes the asy-method and sage-method attributes of project?

[bjones1]

This is an interesting point -- if we point to servers in executables.ptx, then this data is no longer machine-specific/git ignored; in fact, we'd want to provide this data (e.g. which servers to use) with a book and store that in a git tracked file.

Perhaps we store only local paths in executables.ptx, given that these are by definition machine-specific, and server paths in the elsewhere? (The publication file seems like an odd choice to store the webwork server location to me, since this doesn't seem to deal with publication but with the build process.)

[StevenClontz]

I think that's a historical point: before CLI some project-management configurations were put into the publication file (e.g. managed directories, which is why we have to read a publication XML file for that functionality).

(Though on the topic of managed directories, one might argue that we could re-implement that feature for CLI users and put that info in the project manifest...)

[bjones1]

So, how about keeping machine-specific info (paths to local binaries) in executables.ptx, but moving any server-side info to project.ptx?

[bjones1]

Actually, I don't like this -- separating related info (the server location of an Asymptote server, for example) into several files makes it harder for users to understand the relationships. So, I'd still like to keep this in executables.ptx, even though some variants of this file should be under version control while most shouldn't be.

So....I propose what I'd written earlier.

[bjones1]

Another option: stay with a simple executables, that only specifies local executables. Allow the project file to contain a <servers> tag, with something like <server name="asy" method="server">https://address/of/sage.org</server> (the method attribute is optional).

[bjones1]

This is implemented in #511.