Some gardening

Some gardening

[Mojca Miklavec]

Hello,

Here's some more work for you Patrick, in case you get bored.
(I guess I'll soon be removed from the list as a spammer/abuser if I
continue writing mails such as this one :)
What do the others think about it?

# Source browser

Can you "escape" control characters when searching through the source
in ConTeXtgarden? For example, \def\somecommand now has to be written
as\\def\\somecommand. And the search field is slightly small (only 20
characters). Well, I admit, these limitations can all be overcome by
asking Mr. Google for "\def\someveryveryverylongcommand
site:contextgarden.net" or by "grep"-ing on my hard disk.

Also, after the search the right window is empty and sometimes 20 hits
are found on the left. What about adding some context around the
search term? For example one line before and one line after each hit
(like Google does)? Once you have that, the same could be done for
single files (if a specific word appears in one file more than once
than you can select a file and see only the hits found + some lines
before and after). If you also add <a name="linenumber"> to the web
pages with sources, than you can click on a hit and go directly to the
line number where the search term occurs.

# texshow-web

I've just noticed that there's no possibility to describe single
options for the commands.
Take \setuplayout for example. Describing such huge collection of
parameters in plain text is not clear, synoptic any more. It would be
great if there would be a possibility to add descriptions for:
- the command as such (already there)
- every pair of braces (only one for \setuplayout), has to be visible
if it is optional or not
- every parameter inside a single brace
- every single option for that parameter (for example: width=middle
means that ...), default has to be marked

Some classification/hierarchy/labeling of the commands could also be
added, but this has to be thought of well before starting to implement
it. For example "page layout", "floats", "mathematics", "colors",
"metapost", "language", "core functions", ... The top-level
classification could probably be taken from prefixes of the source
files.

Enabling the Wiki functionality (bold, italic, tables ... <texcode>
and <context>) and linking it to the source browser (to the place
where \def\thisspecificcommand is) would also add another
dimensionality. It would probably not be 100% compatible with the
pretty-much-textbased texshow program, but ... I could imagine that
one day something similar as modules.pdf (texshow.pdf) could be made
from that page with pretty good documentation of (all ?) ConTeXt
commands.

The ability to add commands is already there I think (I have never
tried it out yet). What about adding commands for (official and
third-party) modules? It should be separated from the main page, but
still offering the same functionality.

I was also thinking about making some interface for translations of
commands (for example: when a new third-party module is there, someone
could translate it without much effort, some more exotic languages
could be translated step-by-step, and new commands in ConTeXt could be
found quickly and translated - the dutch interface is probably
up-to-date, but I doubt that other translators are constantly checking
if anything new appeared). But these things are much more conservative
(commands may not change once they are translated) and probably not
worth the effort yet.

Finally a "five-minute-work" request after all that philosophizing:
can you add link to the .po files under "special" in texshow-web and a
"submit new .po version" button next to it?

Mojca

Re: Some gardening

[Taco Hoekwater]

Hi there!

Mojca Miklavec wrote:
> Hello,
> 
> Here's some more work for you Patrick, in case you get bored.
> (I guess I'll soon be removed from the list as a spammer/abuser if I
> continue writing mails such as this one :)

I do not think that will happen, but if you keep this up you might
find yourself being volunteered for various tasks :-)

> What do the others think about it?
> 
> # Source browser

I don't normally use this part of the garden, because grepping the
harddisk is a whole lot faster and gives more functionality, but
all your remarks sound nice to me. Not being the one that has to
do the programming, that's an easy thing to say :)

> # texshow-web
> 
> I've just noticed that there's no possibility to describe single
> options for the commands.
> Take \setuplayout for example. Describing such huge collection of
> parameters in plain text is not clear, synoptic any more. It would be
> great if there would be a possibility to add descriptions for:
> - the command as such (already there)
> - every pair of braces (only one for \setuplayout), has to be visible
> if it is optional or not

This is already there, but perhaps a bit too subtle: optional arguments
are typeset using darkred braces and brackets (instead of black)

> - every parameter inside a single brace
> - every single option for that parameter (for example: width=middle
> means that ...), default has to be marked

I believe that information is not in the XML file, but I guess it
should be. Would requires quite some a bit of effort on the data-
entry side (deriving the used defaults from the actual sources).

> Enabling the Wiki functionality (bold, italic, tables ... <texcode>
> and <context>) and linking it to the source browser (to the place
> where \def\thisspecificcommand is) would also add another
> dimensionality. It would probably not be 100% compatible with the
> pretty-much-textbased texshow program, but ... I could imagine that
> one day something similar as modules.pdf (texshow.pdf) could be made
> from that page with pretty good documentation of (all ?) ConTeXt
> commands.

standalone texshow is on the list to be re-done anyway, so I can
make it do whatever texshow-web does without much extra effort
(esp. since it will also become a ruby script).

> The ability to add commands is already there I think (I have never
> tried it out yet). What about adding commands for (official and
> third-party) modules? It should be separated from the main page, but
> still offering the same functionality.

This was on the todo list, IIRC. There is also metapost/metafun and
LaTeX commands to consider. :)

Taco

Re: Some gardening

[Patrick Gundlach]

Hi Mojca,

> Here's some more work for you Patrick, in case you get bored.

Sorry, but I wasn't able to find the last word in my dictionary. 




I have printed out your suggestions(*), the all make much sense to me, so
my plan is to implement them all. I'll report back when I have
something to show.

Some of these suggestions (for example to add wiki like markup to
texshow-web was already on my long-term todo list).

Thank you very much for your suggestions.

Patrick


(*) I never print out mails, but this was just too important

-- 
ConTeXt wiki and more: http://contextgarden.net

Re: Some gardening

[Hans Hagen]

Mojca Miklavec wrote:

> Here's some more work for you Patrick, in case you get bored.
> (I guess I'll soon be removed from the list as a spammer/abuser if I
> continue writing mails such as this one :)
> What do the others think about it?

some day others will start expecting you to help patrick gardening -)

> Take \setuplayout for example. Describing such huge collection of
> parameters in plain text is not clear, synoptic any more. It would be
> great if there would be a possibility to add descriptions for:
> - the command as such (already there)
> - every pair of braces (only one for \setuplayout), has to be visible
> if it is optional or not
> - every parameter inside a single brace
> - every single option for that parameter (for example: width=middle
> means that ...), default has to be marked

default maring is a bit tricky (since it can be \SomeCommand which will they 
blow up context visualizer; in principle, now that we've moved to xml for the 
descriptor, it's easier to add features.

can you give a more verbose example

> The ability to add commands is already there I think (I have never
> tried it out yet). What about adding commands for (official and
> third-party) modules? It should be separated from the main page, but
> still offering the same functionality.

in principle each module should have an associated spec file

Hans

-----------------------------------------------------------------
                                           Hans Hagen | PRAGMA ADE
               Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
      tel: 038 477 53 69 | fax: 038 477 53 74 | www.pragma-ade.com
                                              | www.pragma-pod.nl
-----------------------------------------------------------------

Re: Some gardening

[Mojca Miklavec]

Hans Hagen wrote:
> Mojca Miklavec wrote:
> 
> > Here's some more work for you Patrick, in case you get bored.
> > (I guess I'll soon be removed from the list as a spammer/abuser if I
> > continue writing mails such as this one :)
> > What do the others think about it?
> 
> some day others will start expecting you to help patrick gardening -)

I'm not a reliable person, I don't have as much time and I'm much
slower than "an average ConTeXt developer", but if I know how to do
something and if I have a possibility to do so (access to the
source,...), than I'm willing to contribute - step by step.

> > Take \setuplayout for example. Describing such huge collection of
> > parameters in plain text is not clear, synoptic any more. It would be
> > great if there would be a possibility to add descriptions for:
> > - the command as such (already there)
> > - every pair of braces (only one for \setuplayout), has to be visible
> > if it is optional or not
> > - every parameter inside a single brace
> > - every single option for that parameter (for example: width=middle
> > means that ...), default has to be marked
> 
> default maring is a bit tricky (since it can be \SomeCommand which will they
> blow up context visualizer; in principle, now that we've moved to xml for the
> descriptor, it's easier to add features.
> 
> can you give a more verbose example

Most options are already self explaining, but some are not. A nice
example are serried, broad, packed, ... in \setupitemize. Here it is
necessary to be able to specify what which option does.

An example:
- '\setupitemgroup' - we need place to describe a command and probably
give an example
- there are 4 groups of arguments for this command
    - for each of these groups we would like to specify if the group
is optional or not, what this group does, defaults (if any) and
probably an example
- the third and fourth group have lots of possible arguments (broad,
serried, packed, columns, ... width=...,stopper=..., ...)
    - we have to specify possible combinations of them (broad |
serried | n*broad | n*serried), (packed | unpacked) - broad and
serried may not occur at the same time, while broad and packed may
    - we have to specify if the parameters are "swithches" (they are
present or they are not, like broad, packed) or if they have
parameters, like "headstyle=...".
- In case we have parameters like "headstyle=...", we have to specify
all the alternatives (normal | bold | slanted | boldslanted | ...),
probably note the default value as well. We also have to be able do
describe these alternatives. For example "caps - will typeset the head
of itemization in small caps". And possibility to add an example as
well.

Once again:

% perhaps some "pseudo commands" as this one could be added as well
\setupitemize[.1.][.2.][.3.] 
... equal to/see \setupitemgroup[itemize]

\setupitemgroup[.1.][.2.][.3.][.4.]

Classification (?): setups, different forms of paragraph typesetting
Description: The command is used to control the layout of itemization
environments.
Parameters:

[.1.] {\sl name} - the name of item group for which this setup holds
    {\sl name}
        example: itemize - equal to writing \setupitemize

(optional ?)
[.2.] {\sl number} | each - to which level of itemization the setup should apply
    {\sl number} 
        example: 2 - the second level of itemization
    each - the setup will hold for all the levels

(optional ?)
[.3.] standard [default], (n*broad | n*serried), (packed | unpacked),
stopper, (joinedup | paragraph), (atmargin | inmargin | intext),
autointro, loose, section, columns, (one | two | three | four)
    broad | n*broad - extra horizontal space after symbol
    serried | n*serried - little horizontal space after symbol
        example: someone would probably like to give an example of an
itemization environment with 2*serried option turned on (Wiki-like)
    packed - no white space between items
    unpacked - white space between items
    stopper - use a character like '.' or ':' after the symbol
    joinedup - no white space before and after itemization
    paragraph - no white space before itemization
    atmargin - symbol between margin and text
    inmargin - symbol in margin
    intext - symbol 
    intro - no pagebreak
    loose - ?
    section - ?
    columns - typeset in one, two, three or four columns (two is the default)
    one - will make itemize in one column (where no 'columns' option
is set, this is the default)
    two - will make itemize in two columns (default where 'colums'
option is set)
    three - if columns option is set, it will make the itemize in three columns
    four - if columns option is set, it will make the itemize in four columns
% I have a feeling that the user manual is not very consistent here

[.4.]
\dots

The schema should (I think it does already) support nested commands as
well (like most commands that accept the same parameters as
\setupframed). In this case no change in XML specification is needed,
but it would be nice if texshow would show that parameters as well.

It's difficult to express this in plain text. I'm sorry, my
description is confusing, I know. Also, don't bother about the
mistakes I've made in the description - I don't know what exactly all
of the options do, so I probably gave some wrong descriptions. The
example is just to get the feeling of what I mean with a "description
of parameters on all the levels".

Most of the options DO NOT need additional description as the name is
descriptive enough, but for some of the options an individual
description would be of great help.

> > The ability to add commands is already there I think (I have never
> > tried it out yet). What about adding commands for (official and
> > third-party) modules? It should be separated from the main page, but
> > still offering the same functionality.
> 
> in principle each module should have an associated spec file

Do authors of the modules know that?

Mojca