[toolbox] completion format

[Will R. <ws...@gm...>]

Sorry, Mail.app just nuked half of my [toolbox] messages during a =20
crash. Damn this app.

>  For iTeXMac2, I changed the bullet character to __(ANYTHING)__
>  I adapted the xcode behaviour concerning placeholders.
>  Xcode uses something like
>
>  [myTextView setSelectedRange:<#NSRange aRange#>];
>
>  The problem with this syntax is that < and > are not allowed in xml
>  files...
>  This is why I replaced them with __()__

XML, meh. Anyway, my characters weren't <>, they were =8B=9B, single =20
guillemets. An opening/closing syntax is a marked improvement over my =20=

quickly hacked together solution. I was just following from what =20
TeXShop already provided for.

>  BTW, the actions to select the next and pervious placeholders =20
> should be
>  part of the editor, not an applescript add on.

Again, whatever. Applescript add-ons provide a good way to "suggest" =20
new features. It works and has worked well enough for now, but I =20
agree it would be better to integrate it into the app.

>  If you have some time, see how iTM2 deals with macros at
>  http://itexmac.sourceforge.net/wiki/index.php/Macros.

I'll be investigating iTM2 thoroughly when the final version is =20
released. I don't have time, I'm sorry to say, to help out with bug =20
testing.

>  > New LaTeX packages should be able to write their own command
>  > description file (via the dtx mechanism) which would be preparsed
>  > somewhere such that when a \usepackage is recognised, the extra =20
> macros
>  > can be added to the current pool of "known" commands that the =20
> editor
>  > can prompt for. Ideally, every single user command in LaTeX =20
> should be
>  > completely documented in this way, which would then allow true =20
> syntax
>  > spell checking of LaTeX code.
>
>  This is a detail.

And what a detail!!
No, this is a core concept to making LaTeX easier to use. It =20
shouldn't be up to the user to add every single macro defined to =20
their completions file, nor for a studious individual to hand craft =20
an all-encompassing list.

>  > I imagine an extension to \newcommand (or the LaTeX3 equivalent, =20=

> more
>  > likely) that takes such syntax information for purely metadata
>  > reasons. E.g.,
>  >   \newcommand\mycommand[2]{#1: #2}
>  >   \describemacro\mycommand[1=3Dfirst arg, 2=3Dsecond arg]{This is a =
=20
> macro
>  > for not doing much.}
>
>  Here is my pov.
>
>  You should not rely on metadata in the dtx:
>  1 - if it were easy people would have implemented/used it for a long
>  time.
>  2 - There are some people in the world that would like to see this
>  information in their native languages
>  3 - once the documentation is put in the dtx, you cannot improve it
>  until the next release...

I disagree with each of these statements.
1 - There has never been good coordination between macro writers and =20
frontends.
2 - \describemacro\mycommand[english][1=3Dfirst, 2=3Dsecond]{...}
     \describemacro\mycommand[french][1=3Dune, 2=3Ddeu]{...}
3 - Supplementary files containing \describemacro can be created.

>  4 - it takes time to parse the dtx for just one part of information

Yes, I envision a caching system when the .dtx file is installed.

>  5 - Caching the result of the parsing is quite like not using the dtx
>  at all.

NO!
Using the dtx ensures that the completion file remains up-to-date =20
with the package, and provides that the author of the package =20
specifies how it works.

>  Instead, here is my proposal:
>
>  1 agree on meta markers , I vote for __(*)__ instead of *. The
>  former is not mac centric, is xml compliant and of course is a TeX
>  error.
>  2 agree on a xml format
>  3 agree on a categorization (to uniquely identify the macro...)
>  4 agree on a context dependency (to ensure that \put is used in =20
> picture
>  environments only...)

Sure, all these are insignificant details. I don't see what XML gains =20=

you here, but why not. In a good implementation, the metamarkers =20
would never appear in the TeX source.

>  5 create a web form where anyone can contribute. when posting, this
>  form will just create an xml file containing the appropriate
>  information, including language, format, and so on. Some kind of wiki
>  or spip would help. No need to be a programmer to write doc.

Too hard. Let the package writers deal with it. Docs should only have =20=

to be written once and then everyone can benefit, and the syntax =20
shouldn't be tricky. You want to waste time with a web form?!?

>  6 Any frontend will just do whatever they want with this material =20
> (it's
>  easy with a bit of perl and xslt.).

Yes. An agnostic approach is highly desirable.

>  That way, many people can contribute, and we just have to designate
>  some moderators to accept contributions, modifications...

Are you volunteering to moderate? This is impractical.

>  Remark:
>  Some extensions of this macros/completion design.
>  Suppose you have a macro whose parameters only take a finite =20
> number of
>  values, the user interface should only present these =20
> possibilities. If
>  you have a more complex macro, the user interface might need a better
>  approach.
>  For example,
>
>  \usepackage[__(choose:paper size, a4paper,a5paper,a6paper,letter,
>  legal)__]{geometry}
>
>  would show a small window with a popup to let the user choose the
>  proper paper size.

This is a good idea, and fits in better with extracting this data =20
from the .dtx file. Take a look at xkeyval -- it has a structured =20
approach for defining keyval lists, from which data such as the above =20=

can be extracted.

A dtx file is supposed to be a self-contained implementation and =20
documentation of a package. Moving the macro syntax out of here is =20
madness.

Will