* What about dynamic documentation? @ 2005-12-06 13:19 Jérôme Laurens 2005-12-06 13:59 ` Taco Hoekwater 0 siblings, 1 reply; 6+ messages in thread From: Jérôme Laurens @ 2005-12-06 13:19 UTC (permalink / raw) Hi all, Is is extremely useful for a newbie as I am to have access to the manuals electronically. You just open the pdf and search to obtain what you need. In general, you end up with a command that you have to copy from the pdf then paste to your source file. Another solution is to use the text editor completion feature, which is available only once you know the correct command name, at least the beginning... What I am missing is a button in the pdf itself that would automagically insert the proper code in my source. To be more concrete, here is what could be done (on Mac OS X at least). 0 - Define a data model. 1 - For a reasonnable set of commands, define dedicated GUIs panels. 2 - Write a dedicated browser As there is a huge amount of "reasonnable" TeX and ConTeXt commands, it is -not- reasonnable to fine tune a dedicated GUI for each one. But with some perl I think it would be possible to turn for example the Quick References Manuals into a set of xml files, each one dedicated to its own command. If these files are just HTML forms (modulo the proper style and automagic filter), we have the GUI for free using a web browser. The communication between the browser and the text editor could come from SUBMIT. At least a "copy/paste" phase would be enough. I already have a custom web browser that can insert some text directly in a text editor (iTeXMac) It is based on Mac OS X WebKit. Which means that I will incorporate this browser directly into iTM, but this not the question so far. All this makes points 1 and 2 above acceptable IMHO. The problems come from point 0. I think a good thing would be to create a subsection of the context garden, or another wiki, gathering all the sources. The seed would come from the actual documentation with automagic scripts and people would update at will. Then people would be able to work on a local version using a web sucker. We can imagine searching facilities as well BTW, Sometimes it is necessary to have some output to understand the real effect of a command. This should enter into consideration. How does it sound? ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: What about dynamic documentation? 2005-12-06 13:19 What about dynamic documentation? Jérôme Laurens @ 2005-12-06 13:59 ` Taco Hoekwater 2005-12-06 14:26 ` Adam Lindsay 2005-12-16 7:31 ` Jérôme Laurens 0 siblings, 2 replies; 6+ messages in thread From: Taco Hoekwater @ 2005-12-06 13:59 UTC (permalink / raw) Hi Jérôme, Before you go any further on this, please check out: http://texshow.contextgarden.net The backbone of texshow-web is a set of XML files that are already present in the distribution (look for cont-en.xml) Cheers, Taco Jérôme Laurens wrote: > Hi all, > > Is is extremely useful for a newbie as I am to have access to the > manuals electronically. > You just open the pdf and search to obtain what you need. > > In general, you end up with a command that you have to copy from the pdf > then paste to your source file. > Another solution is to use the text editor completion feature, which is > available only once you know the correct command name, at least the > beginning... > What I am missing is a button in the pdf itself that would automagically > insert the proper code in my source. > > To be more concrete, here is what could be done (on Mac OS X at least). > > 0 - Define a data model. > 1 - For a reasonnable set of commands, define dedicated GUIs panels. > 2 - Write a dedicated browser > > As there is a huge amount of "reasonnable" TeX and ConTeXt commands, it > is -not- reasonnable to fine tune a dedicated GUI for each one. > But with some perl I think it would be possible to turn for example the > Quick References Manuals into a set of xml files, each one dedicated to > its own command. If these files are just HTML forms (modulo the proper > style and automagic filter), we have the GUI for free using a web > browser. The communication between the browser and the text editor could > come from SUBMIT. At least a "copy/paste" phase would be enough. > > I already have a custom web browser that can insert some text directly > in a text editor (iTeXMac) It is based on Mac OS X WebKit. > Which means that I will incorporate this browser directly into iTM, but > this not the question so far. > > All this makes points 1 and 2 above acceptable IMHO. > The problems come from point 0. > I think a good thing would be to create a subsection of the context > garden, or another wiki, gathering all the sources. > The seed would come from the actual documentation with automagic scripts > and people would update at will. > Then people would be able to work on a local version using a web sucker. > We can imagine searching facilities as well > > BTW, Sometimes it is necessary to have some output to understand the > real effect of a command. This should enter into consideration. > > How does it sound? > > _______________________________________________ > ntg-context mailing list > ntg-context@ntg.nl > http://www.ntg.nl/mailman/listinfo/ntg-context ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: What about dynamic documentation? 2005-12-06 13:59 ` Taco Hoekwater @ 2005-12-06 14:26 ` Adam Lindsay 2005-12-16 7:31 ` Jérôme Laurens 1 sibling, 0 replies; 6+ messages in thread From: Adam Lindsay @ 2005-12-06 14:26 UTC (permalink / raw) Taco Hoekwater wrote: > > Hi Jérôme, > > Before you go any further on this, please check out: > > http://texshow.contextgarden.net > > The backbone of texshow-web is a set of XML files that > are already present in the distribution (look for cont-en.xml) Or even here: http://source.contextgarden.net/tex/context/interface/cont-en.xml -- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Adam T. Lindsay, Computing Dept. atl@comp.lancs.ac.uk Lancaster University, InfoLab21 +44(0)1524/510.514 Lancaster, LA1 4WA, UK Fax:+44(0)1524/510.492 -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: What about dynamic documentation? 2005-12-06 13:59 ` Taco Hoekwater 2005-12-06 14:26 ` Adam Lindsay @ 2005-12-16 7:31 ` Jérôme Laurens 2005-12-16 19:56 ` Taco Hoekwater 1 sibling, 1 reply; 6+ messages in thread From: Jérôme Laurens @ 2005-12-16 7:31 UTC (permalink / raw) Le 6 déc. 05, à 14:59, Taco Hoekwater a écrit : > > Hi Jérôme, > > Before you go any further on this, please check out: > > http://texshow.contextgarden.net > Thanks, here is at least a starting point. However, this seems rather far from the pdf manuals and does not really help a newbie as I am. 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. 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. 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. 3 - The description only concerns the command. Each key should also have its own description. Each predefined value should also have its own description. 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. 5 - The command variants might need specials (eg \setupinterlinespace). 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. Finally, it seems that the underlying data model needs more entropy. A - Comments? > The backbone of texshow-web is a set of XML files that > are already present in the distribution (look for cont-en.xml) > > Cheers, Taco > > Jérôme Laurens wrote: >> Hi all, >> Is is extremely useful for a newbie as I am to have access to the >> manuals electronically. >> You just open the pdf and search to obtain what you need. >> In general, you end up with a command that you have to copy from the >> pdf then paste to your source file. >> Another solution is to use the text editor completion feature, which >> is available only once you know the correct command name, at least >> the beginning... >> What I am missing is a button in the pdf itself that would >> automagically insert the proper code in my source. >> To be more concrete, here is what could be done (on Mac OS X at >> least). >> 0 - Define a data model. >> 1 - For a reasonnable set of commands, define dedicated GUIs panels. >> 2 - Write a dedicated browser >> As there is a huge amount of "reasonnable" TeX and ConTeXt commands, >> it is -not- reasonnable to fine tune a dedicated GUI for each one. >> But with some perl I think it would be possible to turn for example >> the Quick References Manuals into a set of xml files, each one >> dedicated to its own command. If these files are just HTML forms >> (modulo the proper style and automagic filter), we have the GUI for >> free using a web browser. The communication between the browser and >> the text editor could come from SUBMIT. At least a "copy/paste" phase >> would be enough. >> I already have a custom web browser that can insert some text >> directly in a text editor (iTeXMac) It is based on Mac OS X WebKit. >> Which means that I will incorporate this browser directly into iTM, >> but this not the question so far. >> All this makes points 1 and 2 above acceptable IMHO. >> The problems come from point 0. >> I think a good thing would be to create a subsection of the context >> garden, or another wiki, gathering all the sources. >> The seed would come from the actual documentation with automagic >> scripts and people would update at will. >> Then people would be able to work on a local version using a web >> sucker. >> We can imagine searching facilities as well >> BTW, Sometimes it is necessary to have some output to understand the >> real effect of a command. This should enter into consideration. >> How does it sound? >> _______________________________________________ >> ntg-context mailing list >> ntg-context@ntg.nl >> http://www.ntg.nl/mailman/listinfo/ntg-context > _______________________________________________ > ntg-context mailing list > ntg-context@ntg.nl > http://www.ntg.nl/mailman/listinfo/ntg-context > ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: What about dynamic documentation? 2005-12-16 7:31 ` Jérôme Laurens @ 2005-12-16 19:56 ` Taco Hoekwater 2005-12-16 23:12 ` Patrick Gundlach 0 siblings, 1 reply; 6+ messages in thread From: Taco Hoekwater @ 2005-12-16 19:56 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: What about dynamic documentation? 2005-12-16 19:56 ` Taco Hoekwater @ 2005-12-16 23:12 ` Patrick Gundlach 0 siblings, 0 replies; 6+ messages in thread From: Patrick Gundlach @ 2005-12-16 23:12 UTC (permalink / raw) Hi Taco and 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. And it was the starting point of contextgarden (and my first web-app). > 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? Good, but let me add a general remark first also on this list. [...] > It could also easily be backported to the XML data. Patrick? yes. put that one on the todo list. > Perhaps the examples could be fed through the Live ConTeXt, just like > the wiki examples? already on the todo list... As my two answers imply, I already have a long todo list for texshow. (I even have two translation updates from Mojca that I haven't implemented yet - sorry). I hope that I will have some time between Christmas and new year for texshow 2. Perhaps we should follow Taco's suggestion to discuss more technical details on the underlying xml description on the dev' list. Patrick -- ConTeXt wiki and more: http://contextgarden.net ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2005-12-16 23:12 UTC | newest] Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2005-12-06 13:19 What about dynamic documentation? Jérôme Laurens 2005-12-06 13:59 ` Taco Hoekwater 2005-12-06 14:26 ` Adam Lindsay 2005-12-16 7:31 ` Jérôme Laurens 2005-12-16 19:56 ` Taco Hoekwater 2005-12-16 23:12 ` Patrick Gundlach
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).