doc: |options| and some functions #355

jlaurens · 2024-06-20T11:04:04Z

documentation improvements: consistency and precision consistent wording in ...aux.lua
*fmt in .gitignore

.gitignore

josephwright · 2024-06-20T11:07:10Z

l3build.dtx

 % variable settings \emph{or} additional code to customize the build
 % process.
 %
 %The example scripts given in Section~\vref{sec:examples} largely cover the required knowledge in Lua programing.
 % For a more advanced usage, one may consult general Lua documentations including \url{https://www.lua.org/manual/5.3/manual.html} and for the few |texlua| specific additions see section 4.2 of the \LuaTeX{} manual available locally with |texdoc luatex| command line or at \url{https://www.pragma-ade.com/general/manuals/luatex.pdf}.
+% Note that |os.execute| is at version 5.1, which is undocumented there.


I don't follow the need for this - LuaTeX includes Lua 5.3.

Except for os.execute that is not at version 5.3 but 5.1.
See https://tug.org/pipermail/luatex/2015-November/005536.htm

josephwright · 2024-06-20T11:07:50Z

l3build.dtx

@@ -368,15 +369,15 @@
 %
 % As well as these targets, the system recognises the options
 % \begin{itemize}
-% \item |--config| (|-c|) Configuration(s) to use for testing
+% \item |--config| (|-c|) Comma or space separated list of configurations to use for testing


The comma/space business is simply standard command line rules based on --XXX or -X options - I don't see that we need to mention this specifically.

This is standard for people who know the standard. The cost of the precision is epsilon.

I mean though that this applies to every command line tool one might use, more or less - e.g. git docs don't say this sort of thing

BTW, it's not comma-or-space, it's just comma - spaces are used to separate arguments

This is not what is implemented.

l3build check -e "foo bar"

this needs clarification either in the implementation of in the documentation

This is there to support the --<long>[=]<option> syntax in addition to the -<short><option> - you can quickly test that --long option option2 treats option2 as a value not an option.

Not really,

--<long>=<option> is managed at line 228

--<long> <option> is managed at line 253

--<short><option> is managed at line 237
id est before line 270. This line is just there to split <option> into a list. The separator is anything that contains a comma or a space.

It was a while ago .. I will check :)

Looking back, I used ,%s since I added argparse-like syntax at all - I guess just an oversight

I've sorted this - just commas count here

l3build.dtx

josephwright · 2024-06-20T11:08:46Z

l3build.dtx

-%       \var{config}        & Table   \\
-%       \var{date}          & String  \\
-%       \var{dirty}         & Boolean \\
-%       \var{dry-run}       & Boolean \\
-%       \var{email}         & String  \\
-%       \var{engine}        & Table   \\
-%       \var{epoch}         & String  \\
+%       \var{config}        & table   \\
+%       \var{date}          & string  \\
+%       \var{dirty}         & boolean \\
+%       \var{dry-run}       & boolean \\
+%       \var{email}         & string  \\
+%       \var{engine}        & table   \\
+%       \var{epoch}         & string  \\
 %       \var{file}          & string  \\
-%       \var{first}         & Boolean \\
-%       \var{full}          & Boolean \\
-%       \var{halt-on-error} & Boolean \\
-%       \var{help}          & Boolean \\
+%       \var{first}         & boolean \\
+%       \var{full}          & boolean \\
+%       \var{halt-on-error} & boolean \\
+%       \var{help}          & boolean \\
 %       \var{message}       & string  \\
-%       \var{names}         & Table   \\
-%       \var{quiet}         & Boolean \\
-%       \var{rerun}         & Boolean \\
-%       \var{shuffle}       & Boolean \\
-%       \var{stdengine}     & Boolean \\
-%       \var{texmfhome}     & String  \\
+%       \var{names}         & table \\
+%       \var{quiet}         & boolean \\
+%       \var{rerun}         & boolean \\
+%       \var{shuffle}       & boolean \\
+%       \var{stdengine}     & boolean \\
+%       \var{texmfhome}     & string  \\


These are deliberately capitalised as the cell starts a statement

Here the type cannot really be capitalized because it refers to 2 things

the output of the lua function type

section 5.6 "Each entry needs a type one of boolean, string or table.
So these are not words, these are case sensitive keywords that cannot be capitalized.
In fact they should be formatted as in section 5.6: I'll commit a change.

Is this section 5.6 still useful?

josephwright · 2024-06-20T11:09:53Z

l3build.dtx

+%   The Lua tables mentionned here are in fact arrays of strings.
+%   From the |build.lua| file, one can modify the string and boolean values,
+%   add or remove entries in arrays. But it is not recommended to affect a
+%   whole new Lua table to |options| nor to its array entries.


I',m not sure what you are getting at: options is set by l3build <options>

Apparently, options is not a read only variable. It is set by l3buil-arguments before build.lua is executed and modified afterwards. Nothing prevents people from saying

options={...}

or

options.engine = {...}

in build.lua or config-....lua. This is an open door to insidious bugs.

josephwright · 2024-06-20T11:10:24Z

l3build.dtx

@@ -1887,32 +1893,32 @@
 %
 % \subsection{Components of \texttt{l3build}}
 %
+% Next functions return $0$ on a successful completion, a non $0$ error code otherwise.


I'm not sure what this is referring to here in 'next'

The functions documented in the section?

I do not really understand the title of the section, as compared to the following section.

jlaurens · 2024-06-21T08:08:28Z

Last commit: In the documentation of |call|, there was

The ⟨options⟩ table should take the same form as the global ⟨options⟩, described above.[...].
Note that any entry for the |target| in this table is ignored.

Not |target| field was exposed in the |options| table.

See discussion in #355.

josephwright · 2024-06-27T08:29:16Z

I think it would be useful if you could split the PR into ones that deal with just one section/concept each - some are easy to agree to, others as we've seen more open ...

documentation improvements: consistency and precision consistent wording in ...aux.lua *fmt in .gitignore

josephwright requested changes Jun 20, 2024

View reviewed changes

josephwright added a commit that referenced this pull request Jun 27, 2024

Correct handling of spaces in options

c0755ab

See discussion in #355.

jlaurens added 3 commits June 27, 2024 13:32

doc: |options| and some functions

3990c9e

documentation improvements: consistency and precision consistent wording in ...aux.lua *fmt in .gitignore

Update l3build.dtx

b101f3b

jlaurens force-pushed the doc-options branch from 80ab990 to a9ae24b Compare June 27, 2024 11:32

jlaurens closed this Jun 27, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: |options| and some functions #355

doc: |options| and some functions #355

jlaurens commented Jun 20, 2024

josephwright Jun 20, 2024

jlaurens Jun 20, 2024

josephwright Jun 20, 2024

jlaurens Jun 20, 2024

josephwright Jun 21, 2024

josephwright Jun 23, 2024

jlaurens Jun 25, 2024

josephwright Jun 25, 2024

jlaurens Jun 26, 2024

josephwright Jun 26, 2024

josephwright Jun 26, 2024

josephwright Jun 27, 2024

josephwright Jun 20, 2024

jlaurens Jun 20, 2024

jlaurens Jun 20, 2024

josephwright Jun 20, 2024

jlaurens Jun 20, 2024

josephwright Jun 20, 2024

jlaurens Jun 20, 2024

jlaurens commented Jun 21, 2024

josephwright commented Jun 27, 2024

doc: |options| and some functions #355

doc: |options| and some functions #355

Conversation

jlaurens commented Jun 20, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jlaurens commented Jun 21, 2024

josephwright commented Jun 27, 2024