[latexrefman-discuss] \newenvironment (non starred) vs \newenvironment* (starred)

[Johannes Böttcher]

I use latex2e.pdf on a regular basis. I consider myself a user who knows 
the basics and tiny bit more. I know l2tabu. I know eqnarray is bad and why.

Documenting the starred versions and how they differ from the normal 
version is important. Giving advice on which one to choose for which 
occasion shouldn't be around. Advice not to overdo it with rules in 
tables shouldn't be here as well.

I think those advice are better suited for an introduction like lshort.


On the other hand, it doesn't matter what advice is put in this manual 
that much. Any advice could be the best in the world ...

I attended a introduction to LaTeX yesterday, for university students. 
The presenter said you need to load package `graphicx' to use the 
`figure' environment. I talked to him and digged around (thanks to 
cgnieder) and ... This was actually to be found in the german version of 
the LaTeX-wikibook. Anybody starting and not knowing about eqnarray etc. 
will find the wikibook first (i know i did) and i think that improving 
that instance by giving the good advice there, and removing the junk is 
more helpful for users. This isn't limited to the german or english 
version.

OT: Vincent, my french is more than a bit rusty. Would you mind reading 
a bit in the french version? Is it littered with bad advice as well?
https://fr.wikibooks.org/wiki/LaTeX


In summary, keeping the straight facts in the manual we are talking 
about, and get the beginners advice where it belongs.


My opinion of course.



On 11/10/2015 11:43 AM, Vincent Belaïche wrote:
>> Shouldn't taboos get to l2tabu instead of a reference manual?
>
> Making a comprehensive list of all taboos in a reference manual is just
> out-of-scope. However, documenting some feature (e.g. starred versions
> of \newcommand, or eqnarry) and not giving _at the same occasion_ any
> information about how it is preferrable or not to use this feature, and
> why, is simply too bad because this means that the reader will get this
> information too late.
>
> VBR,
>      Vincent
>
> 2015-11-10 10:47 GMT+01:00 Johannes Böttcher <johannesbottcher at domain.hid>:
>> Shouldn't taboos get to l2tabu instead of a reference manual?
>>
>>
>> On 11/10/2015 10:00 AM, Vincent Belaïche wrote:
>>>>>
>>>>>    encouraging the starred form, arguments of environments should not
>>>>>    contain multiple paragraphs.
>>>>
>>>>
>>>> Some environments should not, others should.  I don't see any reason to
>>>> either encourage or discourage either form in a reference manual.  It
>>>> should describe the facts of what's available.  -k
>>>
>>>
>>> Well, one of the factual facts is that when you don't need paragraphs in
>>> the argument, then telling it to LaTeX helps you locating easier and
>>> quicker any error. TeX will give out a more explicit error message
>>> because the error is detected earlier in the compilation. This is
>>> exactly what Manuel wrote here:
>>>
>>> https://elzevir.fr/imj/latex/tips.html#ncstared
>>>
>>> So this is a judgement, but it is based on facts.
>>>
>>> Also discouraging eqnarray is another judgement:
>>>
>>> https://elzevir.fr/imj/latex/tips.html#eqnarray
>>>
>>> When there are facts why one should do this way or not this way,
>>> shouldn't we give these facts, that is the purpose of LaTeX tabus...
>>>
>>> http://www.ctan.org/pkg/l2tabu-english
>>>
>>> For instance, should we update \sloppy node to indicate that some people
>>> consider it a LaTeX taboo ?
>>>
>>>     Vincent.
>>>
>>> 2015-11-07 0:30 GMT+01:00 Karl Berry <karl at domain.hid>:
>>>>
>>>>       encouraging the starred form, arguments of environments should not
>>>>       contain multiple paragraphs.
>>>>
>>>> Some environments should not, others should.  I don't see any reason to
>>>> either encourage or discourage either form in a reference manual.  It
>>>> should describe the facts of what's available.  -k
>>>>
>>>>
>>>
>>
>