Skip to content

Commit

Permalink
Make l3doc aware of "kernel" prefix
Browse files Browse the repository at this point in the history 
This allows us to skip the warning about foreign internals in the case
where it is "kernel" and the flag is set for the current .dtx being a
kernel module. We may wish to consider other 'special' cases: perhaps
"debug".

Note at present I've set the .dtx files in l3kernel to ignore "kernel"
prefixes, but not any other code.
  • Loading branch information
@josephwright
josephwright committed Dec 5, 2017
1 parent 85c7db5 commit 82eb988
Show file tree
Hide file tree
Showing 51 changed files with 73 additions and 55 deletions.
2 changes: 1 addition & 1 deletion l3kernel/interface3.tex
View file
Expand Up @@ -38,7 +38,7 @@
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\documentclass{l3doc}
\documentclass[kernel]{l3doc}
\listfiles

\begin{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3alloc.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3basics.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3bootstrap.dtx
View file
Expand Up @@ -118,7 +118,7 @@
% \end{macro}
%</driver|package>
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3box.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3candidates.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3clist.dtx
View file
Expand Up @@ -23,7 +23,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3coffins.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3color.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3deprecation.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
28 changes: 23 additions & 5 deletions l3kernel/l3doc.dtx
View file
Expand Up @@ -686,12 +686,14 @@ and all files in that bundle must be distributed together.
% \g_@@_lmodern_bool,
% \g_@@_checkfunc_bool,
% \g_@@_checktest_bool,
% \g_@@_kernel_bool
% }
% Information about package options.
% \begin{macrocode}
\bool_new:N \g_@@_lmodern_bool
\bool_new:N \g_@@_checkfunc_bool
\bool_new:N \g_@@_checktest_bool
\bool_new:N \g_@@_kernel_bool
% \end{macrocode}
% \end{variable}
%
Expand Down Expand Up @@ -1063,10 +1065,19 @@ and all files in that bundle must be distributed together.
{
\str_if_eq:NNF \l_@@_detect_internals_tl \g_@@_module_name_tl
{
\msg_warning:nnxxx { l3doc } { foreign-internal }
{ \tl_to_str:N \l_@@_detect_internals_cs_tl }
{ \tl_to_str:N \l_@@_detect_internals_tl }
{ \tl_to_str:N \g_@@_module_name_tl }
\bool_lazy_and:nnF
{ \g_@@_kernel_bool }
{
\str_if_eq_x_p:nn
{ \tl_to_str:N \l_@@_detect_internals_tl }
{ kernel }
}
{
\msg_warning:nnxxx { l3doc } { foreign-internal }
{ \tl_to_str:N \l_@@_detect_internals_cs_tl }
{ \tl_to_str:N \l_@@_detect_internals_tl }
{ \tl_to_str:N \g_@@_module_name_tl }
}
}
}
}
Expand Down Expand Up @@ -1361,6 +1372,13 @@ and all files in that bundle must be distributed together.
% \end{macrocode}
%
% \begin{macrocode}
\DeclareOption { kernel }
{ \bool_gset_true:N \g_@@_kernel_bool }
\DeclareOption { stdmodule }
{ \bool_gset_false:N \g_@@_kernel_bool }
% \end{macrocode}
%
% \begin{macrocode}
\DeclareOption { cm-default }
{ \bool_gset_false:N \g_@@_lmodern_bool }
\DeclareOption { lm-default }
Expand All @@ -1369,7 +1387,7 @@ and all files in that bundle must be distributed together.
%
% \begin{macrocode}
\DeclareOption* { \PassOptionsToClass { \CurrentOption } { article } }
\ExecuteOptions { full, nocheck, nochecktest, lm-default }
\ExecuteOptions { full, kernel, nocheck, nochecktest, lm-default }
\PassOptionsToClass { a4paper } { article }
% \end{macrocode}
%
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3docstrip.dtx
View file
Expand Up @@ -35,7 +35,7 @@
\else \csname fi\endcsname
%</gobble>
\def\filename{docstrip.dtx}
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\ExplSyntaxOn
\cs_set_eq:NN \__codedoc_replace_at_at:N \use_none:n
\ExplSyntaxOff
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3drivers.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
%</driver>
%<*driver|package>
%</driver|package>
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3expan.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3file.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\PrintIndex
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3final.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3flag.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3fp-assign.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3fp-aux.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3fp-basics.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3fp-convert.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3fp-expo.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3fp-extended.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3fp-logic.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3fp-parse.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3fp-random.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3fp-round.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3fp-traps.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3fp-trig.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3fp.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\usepackage{amsmath}
\begin{document}
\DocInput{\jobname.dtx}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3int.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3intarray.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3keys.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3luatex.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3msg.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3names.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3oldmodules.dtx
View file
Expand Up @@ -23,7 +23,7 @@
%<*driver|oldmodules>
%</driver|oldmodules>
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down
2 changes: 1 addition & 1 deletion l3kernel/l3prg.dtx
View file
Expand Up @@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
Expand Down

15 comments on commit 82eb988

@FrankMittelbach
Copy link
Member

Choose a reason for hiding this comment

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

are we sure we want "kernel" as an option? This might give the (mis)understanding that this is a general option for anybody to use. Well, maybe not an issue, but it does get a bit blury as you may have to set this option also on l3trial etc and then it is not "yet" kernel.

@josephwright
Copy link
Member Author

Choose a reason for hiding this comment

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

@FrankMittelbach I'm open to better names: this is very much a first pass to get the idea in the code (that we do need to have some way to allow \__kernel in core modules).

@blefloch
Copy link
Member

@blefloch blefloch commented on 82eb988 Dec 5, 2017 via email

Choose a reason for hiding this comment

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

@josephwright
Copy link
Member Author

Choose a reason for hiding this comment

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

Currently l3doc doesn't use keyval methods for options: all of course doable.

@FrankMittelbach
Copy link
Member

Choose a reason for hiding this comment

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

My point was more that I'm not sure that it should be a class option at all so making it an even more general class option doesn't really makes it better in my eyes :-)

anyway, what kind of "allowed-module" would you expect others to use?

@josephwright
Copy link
Member Author

Choose a reason for hiding this comment

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

@FrankMittelbach Ah, you'd prefer to have the internal bool only, and to set it in source3body?

@FrankMittelbach
Copy link
Member

Choose a reason for hiding this comment

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

I was wondering about that, yes. On the other hand I warm up to "kernel" with a documentation that simply states to be used for L3 kernel documentations only (i.e., not for other packages).

@blefloch
Copy link
Member

@blefloch blefloch commented on 82eb988 Dec 5, 2017 via email

Choose a reason for hiding this comment

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

@FrankMittelbach
Copy link
Member

@FrankMittelbach FrankMittelbach commented on 82eb988 Dec 6, 2017 •
edited

Choose a reason for hiding this comment

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

In some sense (although somewhat more work for the programmer) it might actually be best to require "double entry accounting", i.e. have |\codedoc_allow_internals_in:n{<clist_of_modules>}| in the source module and |\codedoc_use_externals_from:n{<clist_of_modules>}| in the target module.

yes cfg would be good. should be a separate issue

@blefloch
Copy link
Member

@blefloch blefloch commented on 82eb988 Dec 6, 2017 via email

Choose a reason for hiding this comment

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

@josephwright
Copy link
Member Author

Choose a reason for hiding this comment

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

@blefloch Hmm: with the 'bundle of modules' business, I'd say the model should be each one has documented interfaces. Now, it does get tricky on where the lines are, but for siunitx I'm aiming to have each sub-part with @@ meaning e.g. siunitx_number, and not using those internals between sub-modules.

@josephwright
Copy link
Member Author

Choose a reason for hiding this comment

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

@blefloch On a .cfg file, I may need to fiddle about a little with l3build to get that to work (the file has to be copied correctly, and it has to go to CTAN as the sources have to compile correctly). @wspr did have a go at it but there were some issues: I guess I need to check how to solve them!

@blefloch
Copy link
Member

@blefloch blefloch commented on 82eb988 Dec 6, 2017 via email

Choose a reason for hiding this comment

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

@josephwright
Copy link
Member Author

Choose a reason for hiding this comment

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

@blefloch The l3doc comparison is made after the @@ substitution I think, so it only checks for __siunitx (probably fair enough: my additional restriction is my own call).

I do know what you mean about 'too much to ask', but my feeling is that this approach is a good way to tell where you need module/submodule breaks, APIs, etc.

@blefloch
Copy link
Member

@blefloch blefloch commented on 82eb988 Dec 6, 2017 via email

Choose a reason for hiding this comment

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

Please sign in to comment.