Talk:Inside ConTeXt

From ConTeXt wiki

It would make sense to have texshow-style documentation for the low-level macros. How about Commands::getparameters et. al. ? Or \getparameters ?

  • yes, it would make much sense, but not in here. We should add them to texshow*, so they would be available not only to the online users but also to etexshow and perhaps other xml based texshow out there.
    • who does the job? The commands have to be given in an xml format, wich is not that trivial (but not complex either)
    • how do we keep the user interface of texshow(-whatever) clean? I would have to program some kind of filter based on keywords - but I wanted to do this anyway :-)
    • I'll post some more on this topic soon, since I'll work on texshow for a bit now

--Patrick Gundlach 11:12, 5 Aug 2004 (CEST)

  • The initial comment was me (I keep getting logged out for discernable reason).
      • I clean up /tmp after one week, so non-cookie-sessions will be deleted then. Is this too short? --pg
    • It seems to me that the best way to do this is to consider the programmer-level macro's to be an extra interface (named 'api').
      • OK, I'll add something. --pg
        • done --pg 01:02, 12 Aug 2004 (CEST)
    • I volunteer for the creation of (at least the beginnings of) the needed XML.
      • great, if you have a few to start with, just mail them to me, OK? pg
    • I propose starting with a really barebones XML file that only lists the macros themselves (no invocation syntax), then add the correct definitions interactively using texshow-web itself.

--Taco

One thing that might be useful to include with this (and possibly with rest of texshow) is documentation of where the commands are defined. Since a lot of commands are defined somewhat implicitly (rather than with code that names them directly -- consider, for instance, what happens if one runs \definestartstop{} or the like), it's often hard to find such things in the code just by grepping for them.

Then again, what would probably be really useful for this is some way to do it that allows us to provide the results back to Hans in a form that he can turn into comments for the code.

--Brooks

Keeping a file::line pointer in the tws/xml file sounds smart. Also, the tws/xml files really should have a date attached to them. Do we need to forward this as a request to Hans?

There is quite a lot of low-level documentation in the source already, I don't think that is the problem. I believe the problem to be that: if you do not know where to look beforehand, it is very hard to discern that a) there is/is not macro with the desired functionality and b) where to find it in the ConTeXt source, if so.

The wiki is ideally suited for writing HOWTO's, but it would be nice if we could link straight to a more formal definition of the used macros. I consider just pointing to the source as the worst possibble way of documenting anything.

Side note: I once started documenting some of ConTeXt 'for programmers', see [syst-gen documentation].

--Taco

I agree that we need a formal description of the low-level user commands in ConTeXt. I'll provide an new interface for texshow-web. But this will be xml-only, so there would no way to use the descriptions in the regular texshow until the regular texshow reads xml. I think that we need a file pointer, but not necessarily an exact line. It would help though if all commands that we describe in the "texshow-api" would be described with the \macros{...} macro. --pg 21:33, 11 Aug 2004 (CEST)