[latexrefman] Document structure [was: \@startsection]

Vincent Belaïche vincent.belaiche at gmail.com
Tue Aug 1 13:29:13 CEST 2017


Feedback below.

Le 31/07/2017 à 23:53, Karl Berry a écrit :
> Re organization: in general, as I've said, I feel we could spend every
> available minute shifting things around to no particular benefit. The
> possibilities for lumping and splitting are endless. I think it is
> better to spend time adding content (as you've both been doing, so
> yay/thanks) than tweaking the organization.
>
> That said, of course when that new content is added, we should do our
> best to insert it in a reasonable structure. I already gave my thoughts
> on \MakeUppercase (Special insertions), such as they were. If you want
> to do something different, I won't quarrel.
>
> Re \makeat..., what comes to mind is to have a new chapter (?!) on
> "Customization" and/or "Programming". I do feel there is a difference
> between describing usage of LaTeX features as they are provided in the
> format, and changing them. For sure, we want to include info on such
> customizations, but the programming infrastructure of LaTeX feels
> different to me than basic syntax.


I agree that we should have a separate programming chapter for advanced
technique where to move the \makeat's & @-commands stuff from §2.4.3.

So to summarize were we are :

1) \makeat's and other @-commands go to a new ``Advanced Programming'' chapter

2) \@startsection is an exception to the rule above, we place it
    under the chap#6 `` Sectionning'' with a reference to the new chapter.


So we will speak about programming in 4 places, but in quite different
ways:

1. § 2.4 LaTeX syntaxe.
2. § 6 definition (basic LaTeX programming)
3. § 3.3 make your own class (could also be just basic LaTeX programming
         inside the class/package)
4. the new chapter (advanced stuff)

For the new advanced stuff chapter we should have :

a) some warning (portability to hevea/tex4ht, non futureproofness,
   etc...)

b) This chapter should have some reference to TeX programming books in
   the beginning of this chapter, like TeXbook, TeXbyTopic, or the
   excellent book Apprendre à programmer en TeX
   (https://progtex.fr/2014/09/22/apprendre-a-programmer-en-tex-le-livre/)

c) This chapter should explain that macros are not functions, so the
   calling prototype may have more arguments than in the command
   declaration because of terminal call. Example

\newcommand*\toto[2]{1=#1, 2=#2, \titi}
\newcommand*\titi[2]{3=#1, 4=#2}
\toto{a}{b}{c}{d}

-| 1=a, 2=b, 3=c, 4=d


d) This chapter should also say something about catcodes. And explained
where and why there are used.

e) We must not go too far, this would be out of scope the document. 


>
> Regarding \@startsection, I think it is good to have it be its own
> section associated with the sectioning commands. 

Ok, I agree, so this is one exeception to the rule, this one does not go
to the new TeX programming chapter. Here the users just have to cut &
paste the examples and adapt them to their needs. No deep TeX
programming knowledge is needed.

> This is one case where I think the new chapter on Sectioning is
> justified. There is plenty more that could be added here eventually.
>
> Lots more could be said, but I have to get back to TUGboat. Sorry. -karl


BTW, as a reminder about methodology, when we move a big piece of text
we should do that in a separate revision with just that change, even if
the compiler is barking about sectionning misalignment. That makes
easier change tracking for aligning translations.


  V.

---
L'absence de virus dans ce courrier électronique a été vérifiée par le logiciel antivirus Avast.
https://www.avast.com/antivirus




More information about the latexrefman mailing list