Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Correct mark-up for non-documented cmds #1325

Open
wants to merge 1 commit into
base: develop
Choose a base branch
from
+28 −22
Open

Correct mark-up for non-documented cmds #1325

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions base/changes.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,11 @@ not part of the distribution.
All changes above are only part of the development branch for the next release.
================================================================================

2024-06-03 Joseph Wright <[email protected]>

* ltfilehook.dtx, ltshipout.dtx
Correct mark-up for commands with no documentation

#########################
# 2024-06-01 Release
#########################
Expand Down
29 changes: 15 additions & 14 deletions base/ltfilehook.dtx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@
%\iffalse
%<*driver,structuredlog>
%\fi
\def\ltfilehookdate{2024/03/13}
\def\ltfilehookdate{2024/06/03}
\def\ltfilehookversion{v1.0o}
%\iffalse
%</driver,structuredlog>
Expand Down Expand Up @@ -750,9 +750,9 @@
% \LaTeXe{} core commands, because of some circular dependencies in the
% kernel we do this only now and not in \texttt{ltfiles}.
%
% \begin{macro}{\InputIfFileExists}
% \begin{macro}{\@input@file@exists@with@hooks}
% \begin{macro}{\unqu@tefilef@und}
% \begin{macro}[no-user-doc]{\InputIfFileExists}
Copy link
Member

@FrankMittelbach FrankMittelbach Apr 10, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sure we don't want to document that one given that it is CamelCase?

TLC3 documents both \IfFileExists and this one and says

The command \InputIfFileExists tests not only whether file exists, but also inputs it immediately after executing then-code. The name file is then added to the list of files to be displayed by \listfiles .

But looking a bit further I guess it is just that the documentation for this command is in another file, so I guess making it no-user-doc here is correct.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's described in ltclass.dtx: we re-define it in ltfilehooks.dtx, but that means there's no user documentation here - I guess we need a 'described elsewhere' marker but for the present no-user-doc seemed the best fit.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes that's what I was thinking also when I realised the the corresponding section was called "patching ....".
Probably a good idea to also add described-elsewhereand use that for such cases, or perhaps even description=ltclass.dtx

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, so perhaps leave these ones 'non-fixed' at the moment until we have a version of l3doc that covers this?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, might be better to change l3doc first, and also fix the missing \MaintainedBy stuff there and then update the 2e .dtx file (for the latter there is an open issue)

% \begin{macro}[int]{\@input@file@exists@with@hooks}
% \begin{macro}[int]{\unqu@tefilef@und}
% \cs{InputIfFileExists} loads any file if it is available so we
% have to add the hooks \hook{file/before} and
% \hook{file/after} in the right places. If the file doesn't
Expand Down Expand Up @@ -1057,8 +1057,8 @@
%
% \subsection{Selecting a file (\cs{set@curr@file})}
%
% \begin{macro}{\set@curr@file,\set@curr@file@nosearch}
% \begin{macro}{\@curr@file,\@curr@file@reqd}
% \begin{macro}[no-user-doc]{\set@curr@file,\set@curr@file@nosearch}
% \begin{macro}[int]{\@curr@file,\@curr@file@reqd}
% \changes{v1.0f}{2021/01/31}{set \cs{protect} to \cs{string} gh/481}
% Now we hook into \cs{set@curr@file} to resolve a possible file
% substitution, and add \cs{@expl@@@filehook@set@curr@file@@nNN}
Expand Down Expand Up @@ -1219,8 +1219,8 @@
%
%
%
% \begin{macro}{\@filehook@set@CurrentFile}
% \begin{macro}{\@kernel@make@file@csname,\@set@curr@file@aux}
% \begin{macro}[int]{\@filehook@set@CurrentFile}
% \begin{macro}[int]{\@kernel@make@file@csname,\@set@curr@file@aux}
%
% \fmi{This should get internalized using \texttt{@expl@} names}
% \begin{macrocode}
Expand Down Expand Up @@ -1275,10 +1275,12 @@
% \end{macro}
% \end{macro}
%
% \begin{macrocode}
%<@@=filehook>
% \end{macrocode}
%
%
% \begin{macro}{\@@_set_curr_file:nNN,
% \@@_set_curr_file_assign:nnnNN}
% \begin{macro}{\@@_set_curr_file:nNN}
% \begin{macro}{\@@_set_curr_file_assign:nnnNN}
% When inputting a file, \cs{set@curr@file} does a file lookup
% (in \cs{input@path} and \cs{l_file_search_path_seq}) and returns the
% actual file name (\meta{base} plus \meta{ext}) in
Expand All @@ -1294,7 +1296,6 @@
%<latexrelease>\IncludeInRelease{2020/10/01}%
%<latexrelease> {@@_set_curr_file:nNN}{Set curr file}%
\ExplSyntaxOn
%<@@=filehook>
\cs_new_protected:Npn \@@_set_curr_file:nNN #1
{
\exp_args:Nf \@@_file_parse_full_name:nN {#1}
Expand All @@ -1311,7 +1312,7 @@
%<*2ekernel>
% \end{macrocode}
% \end{macro}
%
% \end{macro}
%
%
%
Expand Down Expand Up @@ -1803,7 +1804,7 @@
\newcommand\AtVeryVeryEnd {\AddToHook{enddocument/end}}
% \end{macrocode}
%
% \begin{macro}{\BeforeClearDocument}
% \begin{macro}[no-user-doc]{\BeforeClearDocument}
% This one is the only one we don't implement or rather don't have
% a dedicated hook in the code.
% \begin{macrocode}
Expand Down
16 changes: 8 additions & 8 deletions base/ltshipout.dtx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@
%<*driver>
% \fi
\ProvidesFile{ltshipout.dtx}
[2024/02/11 v1.0n LaTeX Kernel (Shipout)]
[2024/06/03 v1.0n LaTeX Kernel (Shipout)]
% \iffalse
%
\documentclass{l3doc}
Expand Down Expand Up @@ -1144,7 +1144,7 @@
%
%
%
% \begin{macro}{\@kernel@after@shipout@lastpage,
% \begin{macro}[no-user-doc]{\@kernel@after@shipout@lastpage,
% \@kernel@before@shipout@background,
% \@kernel@after@shipout@background}
% And here are the internal kernel hooks going before or after the
Expand Down Expand Up @@ -1668,7 +1668,7 @@
%
%
%
% \begin{macro}{\@abspage@last}
% \begin{macro}[int]{\@abspage@last}
% In \cs{@abspage@last} record the number of pages from the last
% run. This is written to the \texttt{.aux} and this way made
% available to the next run. In case there is no \texttt{.aux} file
Expand All @@ -1683,7 +1683,7 @@
% \end{macro}
%
%
% \begin{macro}{\enddocument}
% \begin{macro}[no-user-doc]{\enddocument}
%
% Instead of using the hooks \hook{enddocument} and
% \hook{enddocument/afterlastpage} we add this code to private
Expand All @@ -1700,7 +1700,7 @@
% be wrong but then rerunning the document will give us the correct
% value next time around.
%
% \begin{macro}{\@kernel@after@enddocument}
% \begin{macro}[no-user-doc]{\@kernel@after@enddocument}
% \begin{macrocode}
\g@addto@macro \@kernel@after@enddocument {
\int_compare:nNnT \@abspage@last = \maxdimen
Expand All @@ -1714,7 +1714,7 @@
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@kernel@after@enddocument@afterlastpage}
% \begin{macro}[no-user-doc]{\@kernel@after@enddocument@afterlastpage}
% Once the \cs{clearpage} has done its work inside \cs{enddocument}
% we know for sure how many pages this document has, so we record
% that in the \texttt{.aux} file for the next run.
Expand Down Expand Up @@ -1891,7 +1891,7 @@
%<@@=>
% \end{macrocode}
%
% \begin{macro}{\@expl@@@shipout@add@firstpage@material@@Nn,
% \begin{macro}[int]{\@expl@@@shipout@add@firstpage@material@@Nn,
% \@expl@@@shipout@add@background@box@@n,
% \@expl@@@shipout@add@foreground@box@@n,
% \@expl@@@shipout@add@background@picture@@n,
Expand Down Expand Up @@ -2152,7 +2152,7 @@
% \end{macro}
%
%
% \begin{macro}{\ShipoutBoxHeight,\ShipoutBoxWidth,\ShipoutBoxDepth}
% \begin{macro}[no-user-doc]{\ShipoutBoxHeight,\ShipoutBoxWidth,\ShipoutBoxDepth}
% This is somewhat different from the original in \pkg{atbegshi}
% where \cs{ShipoutBoxHeight} etc.\ only holds the
% \verb=\the\ht<box>= value. This may has some implications in some
Expand Down