Re: [Monotone-devel] Documentation Texinfo XML to Wiki converter
On Wed, Feb 25, 2009 at 07:06:50PM -0500, hend...@topoi.pooq.com wrote: > On Thu, Feb 26, 2009 at 12:09:45AM +0100, Philipp Gröschler wrote: > > Philipp Gröschler schrieb: > > > In the course of the current Mini Summit I spent the afternoon hacking > > > on a (yet still) small XSLT file whose purpose will be the conversion of > > > Monotone's Texinfo Documentation to a set of multiple files which can be > > > used for the Wiki. > > > > > The Lumiera group is struggling with this proboem too -- manageing text > under distributed revision control and making it editable with ordinary > check-in and check-out as well as by wiki. They seem to be in the > process of developing a new wiki (which they are calling uwiki) for this > purpose. They refuse to base it on ikiwiki because they consider perl > unmaintainable. And, by the way, I thing they're using git instead of > monotone. Specifically, their discussion in in the "Tidying up the docs" threads on http://lists.lumiera.org/pipermail/lumiera/2009-February/thread.html > > But the problem is a common one. Yes, indeed it is. > > -- hendrik > > > > ___ > Monotone-devel mailing list > Monotone-devel@nongnu.org > http://lists.nongnu.org/mailman/listinfo/monotone-devel ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
Re: [Monotone-devel] Documentation Texinfo XML to Wiki converter
On Thu, Feb 26, 2009 at 02:45:03PM +0100, Philipp Gröschler wrote: > Thomas Keller schrieb: > > The whole xslt thing is basically a test balloon how well we can convert > > the current texinfo source to wiki markup and if this works out well if > > we use this instead of plain HTML files for the website (or even switch > > completly to a wiki manual, if people agree). The reason for this step > > is because makeinfo is rather limited when it comes to HTML output, you > > cannot rearrange things or add certain needed header / footer parts > > easily to it, _but_ there is an XML output available which theoretically > > could be transformed to anything we want. And exactly this is Philipp's > > work. > > Thanks for clearing this out ;-) My last mail wasn't really what one > would call creative or informational. > > Again, if there are questions, please first take a look at the README > file in the branch I committed. There I tried to sum up my intentions. > Well, at least the important ones. > > Zack Weinberg schrob: > > What is *your* vision for this thing? I don't really understand what > > you have in mind so it's hard for me to evaluate. I think we would > > prefer to keep the master copy of the manual as part of the main > > sources rather than opening it up to wiki-based editing, but that > > doesn't mean support for more different rendering formats is > > uninteresting -- far from it. > > My vision is to get involved in the project in a way that I can help > within my limited spare time/abilities. > > The current state of the package is very experimental, just to show a > way how it *could* be done. Besides the possibility of completely > switching over from the Techinfo Manual to Wiki at some day, I rather > thought of a continous one-way process. The documentation would still be > maintained with Techinfo and new versions would be converted to Wiki > format. The respective resulting parts of the Wiki should then be read > only to prevent concurrent modifications which could not easily be > brought back into the Techinfo part. If text can be modified both on wiki and on original sources, conversion has to be a two-way process, probably moderated. > But that is not my decision. I wanted to show a way how it could be > done, and if there's reasonable demand then I will keep working on it. > So much for the "vision" part ;-) > > Daniel Carosone schrieb: > > The great thing about this work is it (begins to) breaks the coupling > > between purpose and style, which means content can be used for > > multiple purposes regardless of style, in turn meaning that > > "unification" doesn't get confused with "markup conversion". > > > > So, really, yay, and yay again. > > I carefully consider this as a positive response ;-) I first encountered this distinction way back in the days that SGML was an experiment by the American Associatin of Publishers (AAP). Separating the author's job from the book designer's job was the whole point. Since then there's been an explosion of variations on the original design, most of them completely contrary to the original purpose. XML is one of the few that *is* in the right direction, though overly complex. By the way, "AAP" is the Dutch word for "monkey" or "ape", yielding much mirth in Amsterdam, wher I was at the time. > > Yes, XSLT is a nice way to break the border between plain markup and > presentation. I learned to use it about five years ago and I was > astounded by its possibilities. For quite a while I used it for a self > written XML-based servlet engine. > > But besides the magic one could do with XSLT there are also a lot of > limitations. The way a stylesheet works and is processed could drive you > easily into madness. At least it has done so a few times with me. And > some things just do not work. > > Example: I wanted to give the user the possibility to choose the output > format converter at runtime. The first intended way was to get a command > line parameter into a XSLT variable, which then contains the complete > file name of the converter stylesheet and then use this variable with an > include instruction. So to speak, for dynamically chosing the included > converter stylesheet. That one went wrong. XSLT stylesheets are first > compiled completely and then interpreted. There's no way for such > dynamic and runtime dependent behaviour without external programed logic. I forget. Is XSLT the one that has a syntax resembling Scheme? -- hendrik > > > Ah, so much text. I think I should stop here. > > Greetings! > > Philipp > > > ___ > Monotone-devel mailing list > Monotone-devel@nongnu.org > http://lists.nongnu.org/mailman/listinfo/monotone-devel ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
Re: [Monotone-devel] Documentation Texinfo XML to Wiki converter
Thomas Keller schrieb: > The whole xslt thing is basically a test balloon how well we can convert > the current texinfo source to wiki markup and if this works out well if > we use this instead of plain HTML files for the website (or even switch > completly to a wiki manual, if people agree). The reason for this step > is because makeinfo is rather limited when it comes to HTML output, you > cannot rearrange things or add certain needed header / footer parts > easily to it, _but_ there is an XML output available which theoretically > could be transformed to anything we want. And exactly this is Philipp's > work. Thanks for clearing this out ;-) My last mail wasn't really what one would call creative or informational. Again, if there are questions, please first take a look at the README file in the branch I committed. There I tried to sum up my intentions. Well, at least the important ones. Zack Weinberg schrob: > What is *your* vision for this thing? I don't really understand what > you have in mind so it's hard for me to evaluate. I think we would > prefer to keep the master copy of the manual as part of the main > sources rather than opening it up to wiki-based editing, but that > doesn't mean support for more different rendering formats is > uninteresting -- far from it. My vision is to get involved in the project in a way that I can help within my limited spare time/abilities. The current state of the package is very experimental, just to show a way how it *could* be done. Besides the possibility of completely switching over from the Techinfo Manual to Wiki at some day, I rather thought of a continous one-way process. The documentation would still be maintained with Techinfo and new versions would be converted to Wiki format. The respective resulting parts of the Wiki should then be read only to prevent concurrent modifications which could not easily be brought back into the Techinfo part. But that is not my decision. I wanted to show a way how it could be done, and if there's reasonable demand then I will keep working on it. So much for the "vision" part ;-) Daniel Carosone schrieb: > The great thing about this work is it (begins to) breaks the coupling > between purpose and style, which means content can be used for > multiple purposes regardless of style, in turn meaning that > "unification" doesn't get confused with "markup conversion". > > So, really, yay, and yay again. I carefully consider this as a positive response ;-) Yes, XSLT is a nice way to break the border between plain markup and presentation. I learned to use it about five years ago and I was astounded by its possibilities. For quite a while I used it for a self written XML-based servlet engine. But besides the magic one could do with XSLT there are also a lot of limitations. The way a stylesheet works and is processed could drive you easily into madness. At least it has done so a few times with me. And some things just do not work. Example: I wanted to give the user the possibility to choose the output format converter at runtime. The first intended way was to get a command line parameter into a XSLT variable, which then contains the complete file name of the converter stylesheet and then use this variable with an include instruction. So to speak, for dynamically chosing the included converter stylesheet. That one went wrong. XSLT stylesheets are first compiled completely and then interpreted. There's no way for such dynamic and runtime dependent behaviour without external programed logic. Ah, so much text. I think I should stop here. Greetings! Philipp ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
Re: [Monotone-devel] Documentation Texinfo XML to Wiki converter
Zack Weinberg schrieb: > On Wed, Feb 25, 2009 at 3:09 PM, Philipp Gröschler wrote: >> Philipp Gröschler schrieb: >>> In the course of the current Mini Summit I spent the afternoon hacking >>> on a (yet still) small XSLT file whose purpose will be the conversion of >>> Monotone's Texinfo Documentation to a set of multiple files which can be >>> used for the Wiki. >>> >> I just committed the first release of this thing, in a very *pre-alpha* >> state. But better than nothing ;-) For further informations please check >> out "nvm.plasma.doc-wiki-xslt" and have a look the documentation >> provided there. >> >> Please let me know your suggestions and if this thing could have a real >> purpose by someday. Just so that I can keep working on it - or not. > > What is *your* vision for this thing? I don't really understand what > you have in mind so it's hard for me to evaluate. I think we would > prefer to keep the master copy of the manual as part of the main > sources rather than opening it up to wiki-based editing, but that > doesn't mean support for more different rendering formats is > uninteresting -- far from it. The main reason behind it was that we wanted to chain the information in the wiki and in the manual closer together, i.e. have a common layout, a common search functionality, a common markup, easier linkage, and so on. The whole xslt thing is basically a test balloon how well we can convert the current texinfo source to wiki markup and if this works out well if we use this instead of plain HTML files for the website (or even switch completly to a wiki manual, if people agree). The reason for this step is because makeinfo is rather limited when it comes to HTML output, you cannot rearrange things or add certain needed header / footer parts easily to it, _but_ there is an XML output available which theoretically could be transformed to anything we want. And exactly this is Philipp's work. Thomas. -- GPG-Key 0x160D1092 | tommyd3...@jabber.ccc.de | http://thomaskeller.biz Please note that according to the EU law on data retention, information on every electronic information exchange might be retained for a period of six months or longer: http://www.vorratsdatenspeicherung.de/?lang=en signature.asc Description: OpenPGP digital signature ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
Re: [Monotone-devel] Documentation Texinfo XML to Wiki converter
On Thu, Feb 26, 2009 at 12:09:45AM +0100, Philipp Gröschler wrote: > Philipp Gröschler schrieb: > > In the course of the current Mini Summit I spent the afternoon hacking > > on a (yet still) small XSLT file whose purpose will be the conversion of > > Monotone's Texinfo Documentation to a set of multiple files which can be > > used for the Wiki. > > The Lumiera group is struggling with this proboem too -- manageing text under distributed revision control and making it editable with ordinary check-in and check-out as well as by wiki. They seem to be in the process of developing a new wiki (which they are calling uwiki) for this purpose. They refuse to base it on ikiwiki because they consider perl unmaintainable. And, by the way, I thing they're using git instead of monotone. But the problem is a common one. -- hendrik ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
Re: [Monotone-devel] Documentation Texinfo XML to Wiki converter
On Thu, Feb 26, 2009 at 12:09:45AM +0100, Philipp Gr?schler wrote: > Philipp Gr?schler schrieb: > > In the course of the current Mini Summit I spent the afternoon hacking > > on a (yet still) small XSLT file whose purpose will be the conversion of > > Monotone's Texinfo Documentation to a set of multiple files which can be > > used for the Wiki. > > > > I just committed the first release of this thing, in a very *pre-alpha* > state. I saw the commits before this thread, and was curious what you were up to. Alas, I missed the mini-summit this time. But - excellent! As far as output format goes, mdwn or others can be deal with by ikiwiki. The limitations there are around some of the more specific semantic markup: noting that this represents a command, or an option, or a literal vs a variable, and getting this information through to the point where CSS can render it with visual distinctions. Markdown offers some basic notations, and the opportunity to revert to html elements for more detailed cases, but this can be a little disruptive as a document author writing a wiki page (it's a sudden shift from minimal to more extensive internal markup). That is much less an issue if, at least in the first phases, we're talking about keeping the source in texinfo and rendering to something that ikiwiki can consume to produce a better-integrated output on the website (indexing, etc). These are good examples of the discontinuity, by the way, because many of these element types native to texinfo are focused on software documentation, where markdown is more focused on general writing. Longer term, we need to develop a strategy for more unified documentation. That may involve changing the markup source for some components, and potentially integrating your work into ikiwiki (allowing it to read essentially another markup input language). It almost certainly involves unifying the stylesheet, both in terms of the output rendering and the selection of styles available. It also would involve allowing the creation of narrative navigaton paths through the page collection, both as a reading guide online and to structure the generation of offline formats (e.g. PDF output of documents similar to the current manual, in an organised sequence of chapters and sections). This means we'll have pages on the site intended for differnet purposes, generated from a number of mechanisms (including automatic aggregation via some of ikiwiki's tricks), and potentially from sources in different markup styles. The great thing about this work is it (begins to) breaks the coupling between purpose and style, which means content can be used for multiple purposes regardless of style, in turn meaning that "unification" doesn't get confused with "markup conversion". So, really, yay, and yay again. -- Dan. pgpWzv65I69br.pgp Description: PGP signature ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
Re: [Monotone-devel] Documentation Texinfo XML to Wiki converter
On Wed, Feb 25, 2009 at 3:09 PM, Philipp Gröschler wrote: > Philipp Gröschler schrieb: >> In the course of the current Mini Summit I spent the afternoon hacking >> on a (yet still) small XSLT file whose purpose will be the conversion of >> Monotone's Texinfo Documentation to a set of multiple files which can be >> used for the Wiki. >> > > I just committed the first release of this thing, in a very *pre-alpha* > state. But better than nothing ;-) For further informations please check > out "nvm.plasma.doc-wiki-xslt" and have a look the documentation > provided there. > > Please let me know your suggestions and if this thing could have a real > purpose by someday. Just so that I can keep working on it - or not. What is *your* vision for this thing? I don't really understand what you have in mind so it's hard for me to evaluate. I think we would prefer to keep the master copy of the manual as part of the main sources rather than opening it up to wiki-based editing, but that doesn't mean support for more different rendering formats is uninteresting -- far from it. I have to say that my experience with XSLT and related things has been limited, and entirely bad. So I'm not going to be enthusiastic about using XSLT as a key component of my own work process. But this is a judgment on the tools not the results, and I would not say that I love 'makeinfo' either. zw ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
Re: [Monotone-devel] Documentation Texinfo XML to Wiki converter
Philipp Gröschler schrieb: > In the course of the current Mini Summit I spent the afternoon hacking > on a (yet still) small XSLT file whose purpose will be the conversion of > Monotone's Texinfo Documentation to a set of multiple files which can be > used for the Wiki. > I just committed the first release of this thing, in a very *pre-alpha* state. But better than nothing ;-) For further informations please check out "nvm.plasma.doc-wiki-xslt" and have a look the documentation provided there. Please let me know your suggestions and if this thing could have a real purpose by someday. Just so that I can keep working on it - or not. Greetings, Philipp ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
[Monotone-devel] Documentation Texinfo XML to Wiki converter
In the course of the current Mini Summit I spent the afternoon hacking on a (yet still) small XSLT file whose purpose will be the conversion of Monotone's Texinfo Documentation to a set of multiple files which can be used for the Wiki. Unfortunately I have to use a rather new Java based version of Saxon [1] for the transformation process, because neither Gnome's libxml nor Apache Xalan where able to process a XSLT 2.0 template, which is needed for the file splitting and some regular expression stuff. XSLT 1.0 and 1.1 do not have these features AFAIK, or only as vendor specific extensions, which doesn't help either. The current state is that the XSLT searches the whole Texinfo XML file, collects the node hierarchy and therefrom builds up a directory structure with one file for each node (or rather: chapter). Next task would be to take each chapter's XML code and transform it to the desired output format. Currently I have the choice between HTML and the Wiki's own MDWN format, with the possibility to implement both and allow the user to chose between the two before the actual transformation. The number of target formats is not limited and is only depending on how many of them will be needed and, after all, how many complete and working style transformation templates will be created. So the question at the moment is: which output format would be the most useful? According to Thomas Keller there could be some formatting limitations in the Wiki format, but due to lacking experience with that format I can't affirm that. What I can say is that HTML can surely cope with almost everything, but would likely be more time consuming to implement. Also it could be more reasonable to directly create files for the Wiki, since HTML can already be created by makeinfo, though lacking Monotone's Wiki style. That's it for the moment! Greetings, Philipp ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
