Good Morning everyone,
> Am 06.03.2022 um 23:46 schrieb Arash Esbati <[email protected]>: > > Jan Braun <[email protected]> writes: > >> I tried your code, it worked. :-) Thank you very much. > > Thanks for the feedback. You are welcome. Thank you again. >> As you only needed 10 minutes, while mine wasn’t working >> after hours, may I ask your help again? > > Sure, the idea is to get this thing running and add it to AUCTeX :-) Fine. Thank you very much for your generosity! >> Enclosed you’ll find my version, at least I have added a >> lots of comments. > > Thanks. Just FTR: Most of regulars here are used to read diff's, so > please send diff's in future to make progress easier. No problem. I assume `diff -u’ will be the desired way? >> When inserting the user documentation, you should not only use >> the function or variable environments, you should also insert >> a syntax environment therein. > > I've implemented something which asks if you want a syntax environment > as well (see the file attached). It doesn't look if you're in a > documentation or implementation part, it just asks the user. Wow! Thank you again so much! You’re the best. No, I thinks, it works very well! >> Besides asking the user which options to use and which >> variables/macronames to insert, it should also ask, if it should >> insert the syntax environment and prefill it with the macroname in >> vertical bars. > > I had a look at l3doc.pdf section 4.4 Describing functions in the > documentation page 6 and it seems to me that the functions in the > mandatory argument look different than the ones in the syntax env, i.e.: > > \begin{function}[pTF]{\cs_if_exist:N} > \begin{syntax} > \cs{cs_if_exist_p:N} \meta{cs} > \end{syntax} > \meta{description} > \end{function} > > Can we really take the argument and plonk it into a \cs in the syntax > env? My opinion on that is clear. We should do so. My argumentation is such: what is the main goal of docTeX? You should do literate programming and present well documented code. Section 4.4 of the l3doc manual is related to that part of the file, which will be the user manual of that LaTeX package. Environment function and variable are used to typeset these nice margin paragraphs, that contain the name of the described functions and variables. Being typeset that prominently, they are easy to spot for the reader. After having located the function of interest, the reader will surely study, how to use that function to his advantage. This is the aim of the syntax environment, where the syntax of the function and all its arguments are presented. (This is quite similar to the traditional Unix man pages.) To my regret, I consider l3doc.pdf inconsistent, in that the first example starts a section to describe the functions \function_one: and \function_two:. Everything you (as user) should know about this close related functions should be within this function environment. Now to the inconsistency of this example. The new LaTeX3 conventions give each function a so called signature (comparable to real programming languages like C, where you declare in the header file, which arguments this function takes and what type they are). In this case, both example functions have an empty set as signature, i.e. they don’t take arguments! Next comes the syntax environment, which describes a completely (in my eyes) unrelated function \foo_bar:. (Sidenote: the next line „\meta{description}“ really should read <description>, because thats the main goal of the function and variable environments: to hold descriptive text related to the functions (or variables) described therein. It was inserted the usual way as „\meta{description}“, which normally would typeset the <> around the argument. But in this case, a verbatim environment was used, therefore no macro expansion took place.) So I consider this bad style of the l3doc manual and will discuss it on the LaTeX3 mailing list. The next example is somewhat different in that it addresses the new abilities of LaTeX3 functions due to the signature of the functions. With LaTeX (i.e. 2.09 as well as LaTeX2e) you were stuck with the limitations of \newcommand, where you had to define a unique macro name. That resulted in exactly one macro, whose arguments list was also strictly defined by that \newcommand command. With LaTeX3 you now can have a whole bunch of different argument constellations, all defined for one single command. Thats the advantage of separating the macro name from the list of arguments. LaTeX3 thinks of „variants“ and provides „\cs_generate_variant:“ for this exact reason (c.f. LaTeX3 kernel style guide, https://mirror.las.iastate.edu/tex-archive/macros/latex/contrib/l3kernel/l3styleguide.pdf). When describing variants of one function, only the main stem is printed in normal black text color into the margin, while the variants are added in grey color. Have for example a look at chapter 4.3.2 (Defining new functions using parameter text) of interface3.pdf https://ctan.math.illinois.edu/macros/latex/contrib/l3kernel/interface3.pdf. There you will see a bunch of examples, with only one function described in the syntax section. All variants are listed in the margin, while only one abstracted syntax is given, such as "\cs_new:Npn ⟨function ⟩ ⟨parameters ⟩ {⟨code ⟩}“ This is somewhat aimed towards this variants, but in my opinion, it should nevertheless list all variants in the mandatory argument of the function environment. > >> Again, AUCTeX could insert a copy of the macro names, defined in the >> mandatory argument of the >> >> What do you think? > > I'm not sure about this part. It is too hard to predict what will > happen in the macrocode environment so I'm not sure if it is a good idea > to insert the macros names. In my eyes it is, but no one in the world is like my, so I am open to other ideas. > I'm attaching the current state for l3doc.el and doc.el. Please have a > look. Any comments welcome. I will. But while discussing on topics like this: some more crazy ideas of mine? Suppose you start with a naked buffer for file foo.dtx and Emacs changes its major mode to be docTeX. Next you’ll start inserting content into the buffer. As long, as you don’t have added any documentclass and/or packages, docTeX mode is rather restricted in its abilities. Therefore, I guess, the next best thing to do, is to insert the documentclass. By typing C-c C-e AUCTeX will insert the document environment and asks for the documentclass. Of course it suggest the default class, which is by default `article’. I wonder, if you could change that to be `ltxdoc’ in that case (at least, as long, as l3doc hasn’t reached the stable state). I guess, `LaTeX-default-style’ should be a perfect candidate in such cases? PSEUDO-Code: When buffer-mode==docTeX, then setq LaTeX-default-style „ltxdoc“ ... But when inserting a document environment into a DTX buffer/ file, it should at least read like this: ——8<—— %<*driver> \documentclass{l3doc} \begin{document} \DocInput{<buffername>.dtx} \end{document} %</driver> ——8<—— Ao there (To me, this last line presented above, determines the end of the preamble of a DTX file. Everything below that point is usually commented out or part of an macrocode environment.) One of the first things of a DTX file is the command \CheckSum{}. With swiftex.el you could added a function to the buffer-save-hook, which will update the CheckSum every time you save the buffer. Unfortunately, swiftex was last updated at the beginning of the millennium, so I consider it dead. Updating the checksum works, but does not insert the correct checksum, so when running LaTeX on the DTX files, compiling will fail with an error. I haven’t investigated, where the difference between swiftexs and latexs idea of the correct checksums originate. Next is usually the character table. I think, it would be really handy, if there was a AUCTeX function to insert the complete table, not just the naked ”\CharacterTable{}“ command. Here is my actual code to do so: ——8<—— (defun jb-docstrip-insert-char-table () "Insert the '\\CharacterTable' command with all needed chacters." (interactive "*") (move-to-column 0) (insert "% \\CharacterTable{Upper-case \\A \\B \\C \\D \\E \\F \\G \\H \\I \\J \\K \\L \\M\n") (insert "% \\N \\O \\P \\Q \\R \\S \\T \\U \\V \\W \\X \\Y \\Z\n") (insert "% Lower-case \\a \\b \\c \\d \\e \\f \\g \\h \\i \\j \\k \\l \\m\n") (insert "% \\n \\o \\p \\q \\r \\s \\t \\u \\v \\w \\x \\y \\z\n") (insert "% Digits \\0\\1\\2\\3\\4\\5\\6\\7\\8\\9\n") (insert "% Exclamation \\! Double quote \\\" Hash (number) \\#\n") (insert "% Dollar \\$ Percent \\% Ampersand \\&\n") (insert "% Acute accent \\' Left paren \\( Right paren \\)\n") (insert "% Asterisk \\* Plus \\+ Comma \\,\n") (insert "% Minus \\- Point \\. Solidus \\/\n") (insert "% Colon \\: Semicolon \\; Less than \\<\n") (insert "% Equals \\= Greater than \\> Question mark \\?\n") (insert "% Commercial at \\@ Left bracket \\[ Backslash \\\\\n") (insert "% Right bracket \\] Circumflex \\^ Underscore \\_\n") (insert "% Grave accent \\` Left brace \\{ Vertical bar \\|\n") (insert "% Right brace \\} Tilde \\~}\n") ) ——8<—— After having set up all the preliminaries (I am using file templates for that), you’ll start writing the users manual documentation or the code. As explained above: normally every line past the DTX preamble has to start with an percent sign. Thus I am really annoyed, to take care for the percent sign myself. Typing M-j is also inconvenient. Why isn’t Emacs replicating what the percent signs? Another problem I frequently run in: when compiling the DTX file into the pdf document, you’ll usually have to run latex, makeindex (for the index), makeindex (for the changelog) and latex, latex … sometimes enlarged with bibtex. I haven’t found any DTX file, that generates a „normal“ index, which could be generated the usual way. Contrary, if you type C-c C-c (TeX-command-master) and don’t check thoroughly, you might end up in using the suggested AUCTeX default auf „normal Makeindex“. The next time you’ll run latex, you will get lots of errors, due to the incompatible index file. I added this definition to my .emacs file (eval-after-load "tex" '(progn (add-to-list `TeX-command-list ;; The processor "ChangeLog" will run an ;; appropriate MakeIndex command to generate the ;; ChangeLog Index in docstrip related .dtx ;; files. '("ChangeLog" "makeindex -s gglo.ist -o %s.gls %s.glo" TeX-run-command t t :help "Create the ChangeLog in TeXDoc files")) (add-to-list `TeX-command-list ;; The processor "TeXDoc-Index" will run an ;; appropriate MakeIndex command to generate the ;; Index entries in docstrip related .dtx files. '("TeXDoc-Index" "makeindex -s gind.ist -o %s.ind %s.idx" TeX-run-command t t :help "Create the Index in TeXDoc files“)))) to change this manually. It would of course be fine, if AUCTeX would switch to this behaviour automatically, when in docTeX mode. Another theme: Inserting sectioning commands via C-c C-s. Usually, AUCTeX will suggest the last used level, but in DocTeX mode, AUCTeX always suggests the top most \section command, regardless what was used before. Maybe the leading percent signs make the used sections „invisible“? Bye Jan -- Jan Braun (er/ihm) [email protected] === ypchsh /usr/local/bin/emacs === go FORTH now … ===
