Re: What about dynamic documentation?

[Taco Hoekwater <taco@elvenkind.com>]

Hi Jérôme,

> However, this seems rather far from the pdf manuals and does not really 
> help a newbie as I am.

Definately it could be improved. In IT, almost everything is
suboptimal starting the second after it's birth.

Perhaps we should continue this discussion on the developers list,
dev-context@ntg.nl?

It is likely we will spend some other mails on this subject,
and perhaps it is better not to clutter the general list. Anybody
willing to discuss/help out can easily subscribe to that list
(even if just for a while). Is that OK?

> More precisely:
> 
> 0 - Category search is missing. It is well known that searching by 
> contents or by command name won't give the proper result if the search 
> request is not well formed a priori.
> Each command should have a list of associated key words, allowing smart 
> navigation and filtering
> For example, the sectionning commands (including toc, headers and so on) 
> could be gathered in one big category.

That could be as simple as allowing users / viewers to attach one or
two key words/categories to the current commands, I think.  There can
be a predefined set of those, and there will not be all that many.
It could also easily be backported to the XML data. Patrick?

> 1 - The examples oftenly need output to let the user really understand 
> the effect.
> Moreover, the information available in the graphical output is more 
> obvious thus more efficient.

Perhaps the examples could be fed through the Live ConTeXt, just like
the wiki examples?

> 2 - Missing code template(s) to paste into the source, copy/paste does 
> noot help when really needed. Of course, I can grab them from 
> contextgarden but it is there both hidden and not  well formatted.

I am not sure what you mean.

> 3 - The description only concerns the command.
> Each key should also have its own description.

Yes.

> Each predefined value should also have its own description.

Also yes.

(both have been discussed before but never implemented due to lack
  of manpower).

> Then the user interface can provide a layout a la headerdoc or some kind 
> of rollup tooltips.
> 
> 4 - The data storage model for a size range seems weird. The range 5pt 
> ... 12pt is coded with an ordered list of 3 values "5pt" '..." and 
> "12pt" whereas it means an unordered list of 8 values: "5pt", "6pt", 
> ..., "12pt". This latter data model obviously turns into a pop up button 
> with a list of sizes.

It is even a bit weirder. "5pt ... 12pt" usually stands for "any font
size that is already defined using \definebodyfont". Except on the
command itself, of course. There it means: "any font size you wish to
define for use in the other commands that use 5pt ... 12pt".
I'm smiling as I write this :-)

It really should be an abstract type, like "cd:dimension" instead of
those three values.

> 5 - The command variants might need specials (eg \setupinterlinespace).

Yes, the current solution for that command is not very nice. But
there are more than a few commands with such variant calling
conventions, and it is hard to come up with a nice-looking solution.
Suggestions for solutions are welcome.

> 6 - Sometimes the acceptable values depend on the context (eg arguments 
> of \ref), it means that all the relevant information is not static and 
> the data model should provide some entry points. But at first glance 
> this is a very advanced feature which cost might be unaffordable.

You mean crossover functionality with reftex/auctex style programs?
Would be nice to have I assume, but hard to do portably, and not
really worth the effort if it cannot be done in a portable manner.
(always speaking from my point of view, of course. YMMV)

> Finally, it seems that the underlying data model needs more entropy.

Thermodynaics says it will probably move in the right direction, once
it starts moving ;-)

Cheers, Taco