Hi everyone,
At present I think the "Math Macros" section is extremely confusing, especially
for someone that hasn't used LaTeX much/at all. "Self-defined functions" also
needs changing. Here are my suggestions, which I'm happy to implement myself if
there is agreement:
* S22.1 describes \newcommand in detail. Since LyX math macros basically
replace \newcommand completely, I don't see any need for this section at, so I
propose it's scrapped. If people want to use explicit LaTeX instead of LyX
features, then that's up to them, not the job of LyX documentation.
* S22.2, which actually describes LyX math macros, starts with an argument that
it is better to them than \newcommand. Again, I think we should scrap this,
since the whole premise of LyX is to use graphical features rather than raw
LaTeX. We don't tell people that it's better to use a layout than ERT
"\section{foo}", or a LyX math equation instead of ERT "$x$", we assume they
know that. If you already know about \newcommand, it should be clear why LyX
macros are better to use just from its own explanation.
* I do agree that we need to *mention* that this feature is the LyX version of
\newcommand. We also need to mention the differences of the LyX form: it is
more
like \renewcommand since it doesn't matter if it's already defined, and it has
global scope (but not just said like that, explained properly). In my opinion
this should be a single paragraph, in a note, near the start of the section
(after a paragraph explaining LyX math macros in a LaTeX-independent way).
* S22.2 talks in detail about arguments right from the start. I think that we
should split a detailed discussion of arguments into a separate subsection.
Combined with the above changes, this means there are only two subsections: the
first should first give an example with no arguments, then a simple example
with
one compulsory argument; the second explains arguments in more detail.
* Mention should be made of the LyX display feature of math macros. A good
example is \sgn TeX:"\operatorname{sgn}" LyX:"\mathrm{sgn}".
* In S15.2 "Self-defined functions", the suggested way of getting a one-time
function is "\,\mbox{sgn}". Ugh! The correct way is "\operatorname{sgn}", or
"\operatorname*{lim\,inf}" for limit-style script placement.
* For repeated use, "\DeclareMathOperator" is given. We should be promoting the
use of LyX math macros instead. Indeed if we use the example I just mentioned
in
S22.1, then having explained "\operatorname" and "\operatorname*" we can then
just refer to S22.1 for how to use them repeatedly. Ok, we should say slightly
more than that so that it's not missed as people skim through it. Repeating the
image showing how to enter the example in LyX would do, I think.
What do people think? I could actually make these changes and attach these
sections in a LyX file, if it helps.
Jim
