Am 17.06.10 15:11, schrieb Mojca Miklavec:

On Wed, Jun 16, 2010 at 19:56, Wolfgang Schuster wrote:

...

Hi,

i plan to update cont-en.xml with changes in mkiv (new keys and commands) but i'm unsure if it's good to mix mkii and mkiv. I think it's to make a separate definition file for mkiv which contains the extra keys for the commands (e.g. sectionsegments for \setuphead) and use the current one for mkii only.

My opinion (though at the end you may do it either way): I would put a special key to either each command or each option that would clarify "mkii only" or "mkiv only" or "both". If command is completely different, for example \usetypescript[name][ec] in mkii vs. \usetypescript[name] in mkiv one could define two commands and label one as "mkii only" and the second one as "mkiv only".

There might be also another thing worth keeping in mind. Some commands may be valid, but useless in mkiv. It might make sense to label those as such.

Even though the fact that "mkii is frozen" might be true, most of valid options are still missing in those xml files.

Again: I would keep a single file with a new key that would specify in "which mark" commands works and/or makes sense. That way it would be a tiny bit easier to maintain both versions synchronized (assume that you will want to document a new command that's also present in MKII - are you going to remember that you also need to update MKII; and then one will see a command in MKIV, but will have no idea whether the absence in MKII means that somebody forgot that command or that it's simply not present/working there).

But since you are planning to work on it, it's up to you to decide. That was only my opinion.

For the start i'll go only through the mkiv files and use a separate file for them, maybe later i can compare the mkiv with the mkii options and use hans approach because tagging each key and command is a lot of work. Wolfgang

On Fri, Jun 18, 2010 at 10:58, Hans Hagen wrote:

On 17-6-2010 3:11, Mojca Miklavec wrote:

...

Even though the fact that "mkii is frozen" might be true, most of valid options are still missing in those xml files.

well, 'most' is not fair

I'm sorry, I probably wanted to say that "most of undocumented options are missing in those xml files" :) :) :) There is no doubt that the great majority and in particular all the most important commands are present. Mojca

Am 23.06.10 09:35, schrieb Peter Münster:

On Wed, Jun 16 2010, Wolfgang Schuster wrote:

...

i plan to update cont-en.xml with changes in mkiv (new keys and commands)

Hello Wolfgang,

Since Hans said "documentation about tex can best be done in tex", I've put my ideas into some files here:

http://pmrb.free.fr/tmp/context-commands/

What do you think about that?

I agree that tex is the best tool to document tex but cont-en.xml is only a tool to help in the documentation and i can't see a big advantage to rewrite it in pure tex. The explanation for the keys/options is another thing but they are not what i'm working on. My files are now available here: http://bitbucket.org/wolfs/setup Wolfgang

Am 30.06.10 12:57, schrieb Marius:

Hello,

I think that the best way is to put command syntax description just before its definition in the context file. This way it will be easier to keep it always in sync with the code. And most important point here is that it must be in sync always. If it is, then we can just generate cont-en.xml and other cont-xx.xml files, but also have a syntax checker!

Just imagine:

context --check-syntax myfile.tex

shows you which options or commands are experimental, deprecated, and which are unrecognized, and suggests the command or option to fix that.

What do you think?

The idea is not bad but who is going to do this? Hans implemented in mkiv the function to check assignments list of valid keys but this function isn't used because nobody writes the necessary lists which contexts requires to do these checks and the same will happen with the system you suggest. Wolfgang

On 07/02/2010 11:28 AM, Peter Münster wrote:

On Fri, Jul 02 2010, Wolfgang Schuster wrote:

...

The idea is not bad but who is going to do this? Hans implemented in mkiv the function to check assignments list of valid keys but this function isn't used because nobody writes the necessary lists which contexts requires to do these checks and the same will happen with the system you suggest.

That's why I'm eventually going to do this: http://archive.contextgarden.net/message/20100508.204345.b5003312.en.html

Perhaps using tex-files like this: http://pmrb.free.fr/tmp/context-commands/

Perhaps in this directory: http://foundry.supelec.fr/svn/contextman/context-commands So that everybody can contribute via svn.

But before doing that effort, I still need a bit more feedback...

I think this will be a wasted effort. I predict that any future version of context that will be able to do syntax checking is going to be based on lua for the verification process, not tex macros. Possibly the internal structure could also be read in from structured comments in the actual source files as opposed to the current external xml files (not a bad idea as it increased the chance of everything staying up-to-date). But even in that case, those comments are much more likely to be lua or compressed ascii code than actual tex syntax because interpretation will be done mostly by lua code. Best wishes, Taco

On Fri, Jul 2, 2010 at 1:21 PM, Taco Hoekwater wrote:

I think this will be a wasted effort. I predict that any future version of context that will be able to do syntax checking is going to be based on lua for the verification process, not tex macros.

There is already an example implementation of comments reading. http://gitorious.org/context/context/blobs/master/scripts/context/lua/mtx-mo... cd tex/context/base mtxrun --script modules --process page-txt.mkiv see the resulting page-txt-mkiv.ted and page-txt-mkiv.pdf files.

Possibly the internal structure could also be read in from structured comments in the actual source files as opposed to the current external xml files (not a bad idea as it increased the chance of everything staying up-to-date).

So, reading of comments could be implemented based on this example.

But even in that case, those comments are much more likely to be lua or compressed ascii code than actual tex syntax because interpretation will be done mostly by lua code.

What do you mean by saying "to be lua or compressed ascii code"? I can't imagine how it may look like, as I am new to the lua. Could you, please, give an example? I will try to code a rough draft, but at first it needs to be decided what syntax we will use for these comments. Regards, Marius

Am 05.07.10 12:26, schrieb Taco Hoekwater:

On 07/05/2010 11:44 AM, Marius wrote:

...

On Fri, Jul 2, 2010 at 1:21 PM, Taco Hoekwater wrote:

...

I think this will be a wasted effort. I predict that any future version of context that will be able to do syntax checking is going to be based on lua for the verification process, not tex macros.

...

There is already an example implementation of comments reading.

http://gitorious.org/context/context/blobs/master/scripts/context/lua/mtx-mo...

cd tex/context/base mtxrun --script modules --process page-txt.mkiv

see the resulting page-txt-mkiv.ted and page-txt-mkiv.pdf files. Yes, this functionality has been around for ages, and is the basis of luigi's typeset source documentation project:

http://foundry.supelec.fr/gf/project/modules And a similar mechanism is available to document lua files but it use xml markup rather than tex (and this since the beginning). One possible extension would be:

%X %X cd:sequence %X %X %X cd:arguments %X %X %X %X %X

But that is rather verbose and needs processing to create useful solution. Another possibility using actual lua could be:

%X showbodyfont = { %X seq = { string = "showbodyfont" }, %X arg = { keywords = { %X n=1,list=true, optional=true, %X inherit={ name = "setupbodyfont", n = 1}}}}

Essentially the same information, but shorter, and it could be loaded into lua directly using 'loadstring'. Or there could be a more TeX-like approach looking like this:

%X \cmd{showbodyfont}([...,...,...])->#1:\inherited{setupbodyfont}

to be parsed by a bit of lua code.

It all depends on what Hans is most comfortable with in keying in, because if Hans doesn't like it the chances of anything like this remaining up-to-date are about zero. I'm against storing the command definition in the relevant files because

The 'key' checker for \getparameters in mkiv is lua based. the definitions are meant for documentation and it's nonsense in this way because you need sometimes references to other commands and who should you show a command for spacing which is written in a font file. Another problem is that big macros like \section or \setuphead are split over different files (strc-sec.mkiv, strc-doc.mkiv, strc-doc.lua and strc-ren.mkiv) and when you store the \section definition now in strc-sec.mkiv but make a change in strc-ren.mkiv you will forget to add the change in the definition file are too high. From your two different variants i prefer the lua solution because it's closer to the current xml version and it's easier to add variants of a command (e.g. \setupinterlinespace[small] and \setupinterlinespace[line=...]) Wolfgang

On 6-7-2010 8:23, taco wrote: sorry for delays in responding ... i'm still in the process of fixing hardware / installations etc

Wolfgang Schuster wrote:

...

I'm against storing the command definition in the relevant files because the definitions are meant for documentation and it's nonsense in this way because you need sometimes references to other commands and who should you show a command for spacing which is written in a font file.

fyi: long ago it started like that: a \startsetup... definition as part of the tex files but it was a pain togenerate the lists that way

Well, they could be extracted automatically to a normal lua file, but you had a good point about the \section etc later on, so a separate file would probably be better indeed.

i'm not so sure if i want to abandon the xml file (yet) as theres nothing wrong with xml per se ... it's no big deal to generate lua from it if needed (both are as unreadable although with somenamespacing we could probably share more in lua but at the cost of readablity (and i'm really sensitive to formating of such files -) needs more thinking as changes in that area should not happen too often we can consider splitting up things but as already mentioned it's hard to come up with a devision based on the tex files ... ok, in due time we might get more granularity; an option is to make files per block: page, strc, core, ... concerning the documentation in the lua files (not that much and currently in xml) ... it could be just context code as it then permits embedding examples Hans ----------------------------------------------------------------- Hans Hagen | PRAGMA ADE Ridderstraat 27 | 8061 GH Hasselt | The Netherlands tel: 038 477 53 69 | voip: 087 875 68 74 | www.pragma-ade.com | www.pragma-pod.nl -----------------------------------------------------------------

Am 11.09.2010 um 22:41 schrieb Marius:

...

The idea is not bad but who is going to do this? Hans implemented in mkiv the function to check assignments list of valid keys but this function isn't used because nobody writes the necessary lists which contexts requires to do these checks and the same will happen with the system you suggest.

Please, point me to the function you are talking about.

The function is implemented in mult-chk.mkiv, here is a example: \starttext \startbuffer \getcheckedparameters[MyTest][MyNamespace][a=1,b=2,c=3,d=4,crap=whatever] \MyNamespacea\quad \MyNamespaceb\quad \MyNamespacec\quad \MyNamespaced\quad crap is \ifdefined\MyNamespacecrap\else un\fi defined \stopbuffer \enablecheckparameters \setvalidparameterkeys[MyTest][a,b,c,d] \getbuffer \par \addvalidparameterkeys[MyTest][crap] \getbuffer \par \stoptext As a user you don’t have to care about all the stuff, all you need is \enablecheckparameters in your document. Wolfgang