From goodger@users.sourceforge.net Sat Jun 1 04:09:39 2002 From: goodger@users.sourceforge.net (David Goodger) Date: Fri, 31 May 2002 23:09:39 -0400 Subject: [Doc-SIG] Updates to Docutils Message-ID: In the latest round of checkins I added "header" & "footer" elements to the Docutils DTD, within an optional "decoration" element, positioned right after "docinfo". These elements are to be used for page navigation stuff, notes, time/datestamp, etc. The need for additional "decorations" may be discovered in the future. I'm not sure this is the correct approach; please speak up if you have a better idea. I've implemented the corresponding --generator, --date, --time, and --source-link options, along with their --no-* compliments. (Optik is proving very useful and easy.) Also a new transform ``docutils.transforms.universal.Decorations``, and support in the HTML writer. For those of you already using Docutils on your web sites, please consider adding the --generator/-g and --source-link/-s options when you generate HTML, to help spread the word. See the bottoms of the Docutils pages for examples. ``tools/html.py --help`` documents all implemented options. Download the latest snapshots from: - http://docutils.sf.net/docutils-snapshot.tgz - http://docutils.sf.net/docutils-sandbox-snapshot.tgz -- David Goodger Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ From aahz@pythoncraft.com Sun Jun 2 21:36:47 2002 From: aahz@pythoncraft.com (Aahz) Date: Sun, 2 Jun 2002 16:36:47 -0400 Subject: [Doc-SIG] ASCII to Word? Message-ID: <20020602203646.GA5174@panix.com> All right, I'm ready to get started on writing my book. My publisher wants the document in Word format. I'm starting in some form of ASCII, quite likely reST. What do people recommend as the best path for getting from here to there? Is anyone else using reST for long technical documents? In the absence of better advice, I'm going to convert to OpenOffice's XML format, then use OpenOffice to convert to Word. One way or another, I'm assuming that Python will be used for at least the first stage of translation. -- Aahz (aahz@pythoncraft.com) <*> http://www.pythoncraft.com/ "In the end, outside of spy agencies, people are far too trusting and willing to help." --Ira Winkler From phoengeist38259@arcor.de" Entschuldigen Sie bitte die Störung! Mir ist etwas zu Ohren gekommen. Eine relativ aussergewöhnliche Gerüchteküche, aus der man mir ein schwerverdauliches Süppchen vorgesetzt hat, ist der Grund meiner Mail. Unappetitlich ist gar kein Ausdruck! Ist es möglich auf funktechnischem Wege(in welchen Frequenzbereichen?) jemanden zu beeinflussen oder zu manipulieren? Oder sogar zu schikanieren und terrorisieren? Unter dem Motto:"Einen am Sender?Nich ganz alleine? Kleine Mannim Ohr?Falsche Wellenlänge?Bohnen in den Ohren? Auf den Zahn gefühlt(Amalgam)?Mal unverbindlich reinhören? Der Pullacher Wanzentanz? Ist das Spinnerei?Das geht doch gar nicht,oder? Und wenn wie sieht das ethisch moralisch aus? Zur technischen Seite der Sache gibt es zwar Berichte und Webseiten: Totalitaer,de - Die Waffe gegen die Kritik http://www.raum-und-zeit.com/Aktuell/Brummton.htm http://www.fosar-bludorf.com/Tempelhof/ http://jya.com/haarp.htm http://www.zeitenschrift.at/magazin/zs_24_15/1_mikrowaffen.htm http://www.bse-plus.de/d/doc/lbrief/lbmincontr.htm http://home.nexgo.de/kraven/bigb/big3.html http://w3.nrl.navy.mil/projects/haarp/index.html http://cryptome.org/ http://www.raven1.net/ravindex.htm http://www.calweb.com/~welsh/ http://www.cahe.org/ http://www.parascope.com/ds/mkultra0.htm http://www.trufax.org/menu/mind.html http://www.trufax.org/menu/elect.html http://mindcontrolforum.com/ http://www.trufax.org/menu/elect.html usw. usw. usw. ,aber,das kann doch nicht sein,das soetwas gemacht wird,oder? Eine Menschenrechtsverletzung sonder gleichen!?! Ist es möglich,durch Präparation,der Ohren und im Zusammenspiel mit eventuell vorhandenem Zahnersatz? Mit relativ einfacher Funktechnik?? In diesem Land?Hier und heute??? Unter welchen Motiven? Wo ist eigentlich die Abteilung 5 des BND und des Verfassungsschutzes? Kann es sein,daß es Leute gibt,die dem BND/Verfassungsschutz,auf funktechnischem Wege permanent einen Situationsbericht abliefern,ohne es selbst zu merken,im Kindesalter machbar gemacht?? Werden durch solche inoffiziellen Mitarbeiter,beim BND und Verfassungsschutz,nach Stasimanier, Informationen von und über,rein theoretisch, jeden Bundesbürger,gesammelt? Gibt es dann noch ein Recht auf Privatsphere? Wer kontrolliert eigentlich den BND,MAD und Verfassungsschutz auf Unterwanderung??? In der Mail geht es mir eigentlich um die Frage,ob es kriminellen Elementen, aus dem Motiv der Bereicherung,oder Gruppierungen aus ideologischen Motiven, möglich ist ,sich Wissen und Technik anzueignen,die zu anderen Zeiten, aus anderen Motiven(Westfernsehen?),entwickelt wurde. Und stellt der technische Wissensstand, der der Allgemeinheit bekannt ist wirklich das Ende der Fahnenstange dar? Ist es denn nicht kriminellen Elementen genauso möglich, ich sage das jetzt mal verharmlost und verniedlichend, einzelne Personen oder Gruppen mit relativ einfachen Mitteln, aus welchen Motiven auch immer, auszuspionieren? Und stellt diese "Ausspioniererei" nicht einen erheblichen Eingriff in die Privatsphäre dar? Ist es möglich einzelne Personen oder Gruppen, eine Akzeptans einer gewissen Öffentlichkeit(suggeriert?), die z.B. mit Hilfe von Internetseiten,wie zum Beispiel dem "Pranger"geschaffen werden könnte, mal vorausgestzt,zu terroriesieren und oder zu schikanieren, und das in aller (suggerierten)Öffentlichkeit?Haben die Leute die da am Pranger, oder auf irgendeiner anderen Seite verunglimpft,oder gar Verleumdet werden, eigentlich eine Chance zur Gegenöffentlichkeit?Ist das nicht Rufmord? Vor einigen Jahren bin ich per Zufall auf die Seite "Der Pranger" gestoßen, damals lief das noch nicht unter dem Deckmantel der Partnervermittlung. Können sich einzelne Personen,oder Interessengemeinschaften, aus reinem Selbstzweck,solcher Seiten bedienen, um unter dem Deckmantel einer fragwürdigen Zivilkourage, durch anzetteln irgendwelcher Hetzkampagnen,eigene, ganz persöhnliche Interessen durchsetzen? Können solche Seiten zur Koordination von kriminellen machenschaften dienen? Die Frage,ist es Möglichkeit oder Unmöglichkeit,technisch und gesellschaftlich, einzelne Personen,oder auch Gruppierungen,aus einer kriminellen/ideologischen Energei heraus,zu manipulieren oder zu beeinflussen,terrorisieren oder zu schickanieren,und zwar gezielt. Zielgruppenmanipulation durch Massenmedien sind alltägliche Manipulation, der mansich,mehr oder weniger,entziehen kann. Wird das Recht auf Privatsphäre,schleichend,tiefenpsychologisch, durch Sendungen,wie,zum Beispiel "Big brother",untergraben? Sollte bei einem der Angemailten ein gewisser Wissensstand zum Thema vorhanden sein, wäre ich über Hinweise zum Thema froh. Auf der Suche nach Antworten auf meine Fragen maile ich verschiedene Adressen aus dem Internet an, und hoffe aufkonstruktive Antworten und Kritiken. Über einen Besuch auf der Seite würde ich mich freuen. Sollten Sie von mir mehrfach angeschrieben worden sein,so bitte ich Sie,mir dies zu entschuldigen, das war nicht beabsichtigt. Der Grund für meine Anonymität ist die Tatsache, daß bei derlei Fragenstellerei, verständlicherweise,schnell der Ruf nach der Psychatrie laut wird. Was auch Methode hat(ist). Sollten Sie die Mail als Belästigung empfinden, möchte ich mich hiermit dafür entschuldigen! Big brother is watching you? Excuse please the disturbance! Me something came to ears. A relatively unusual rumor kitchen, from which one put forward to me a heavydigestible soup, is the reason of my Mail. Unappetizing is no printout! Is it possible on radio Wege(in for which frequency ranges?) to influence or manipulate someone? Terrorize or to even chicane and? Under the Motto:"Einen at the Sender?Nich quite alone? Small Mannim Ohr?Fal Wellenlaenge?Bohnen in the ears? On the tooth clean-hear gefuehlt(Amalgam)?Mal witthout obligation? The Pullacher bug wanzentanz? Isn't the Spinnerei?Das goes nevertheless at all, or? And if as looks ethicalally morally? For the technical page of the thing there is to report and web page: Totalitaer,de - Die Waffe gegen die Kritik http://www.raum-und-zeit.com/Aktuell/Brummton.htm http://www.fosar-bludorf.com/Tempelhof/ http://jya.com/haarp.htm http://www.zeitenschrift.at/magazin/zs_24_15/1_mikrowaffen.htm http://www.bse-plus.de/d/doc/lbrief/lbmincontr.htm http://home.nexgo.de/kraven/bigb/big3.html http://w3.nrl.navy.mil/projects/haarp/index.html http://cryptome.org/ http://www.raven1.net/ravindex.htm http://www.calweb.com/~welsh/ http://www.cahe.org/ http://www.parascope.com/ds/mkultra0.htm http://www.trufax.org/menu/mind.html http://www.trufax.org/menu/elect.html http://mindcontrolforum.com/ http://www.trufax.org/menu/elect.html usw. usw. usw. but, that cannot be nevertheless, which is made soetwas, or? A violation of human rights resemble special!?! Is it possible, by preparation, the ears and in interaction with possibly available artificial dentures? With relatively simple radio engineering?? In this Land?Hier and today??? Under which motives? Where is the department actually 5 of the BND and the protection of the constitution? Can it be that there are people, which deliver the Federal Intelligence Service/protection of the constitution, on radio way permanently a situation report, without noticing it, in the infancy feasiblly made? By such unofficial coworkers, with the BND and protection of the constitution, after Stasimanier, is information collected of and over,purely theoretically, each Federal citizen? Is there then still another right to Privatsphere? Who actually checks the BND, WAD and protection of the constitution for infiltration??? Into the Mail actually concerns it to me the question whether it criminal items, from which motive of enriching, or groupings from ideological motives is possible, to acquire itself knowledge and technique which were developed at other times, from other Motiven(Westfernsehen?).And does the technical knowledge status place, to that the public admits is really the end of the flag bar? Is it not to criminal items just as possible, I legend that now times played down and does nice-end, individual persons or groups with relatively simple means, to spy from whatever motives always? And doesn't this " Ausspioniererei " represent a substantial intervention into the privatsphaere? It is possible individual persons or groups, one acceptance to of a certain Oeffentlichkeit(suggeriert?), e.g. by Internet pages, how for example the " Pranger"geschaffen could become, times vorausgestzt, to terroriesieren and or chicane, and in everything (the people suggerierten)Oeffentlichkeit?Haben there at the Pranger, or on any other page to be reviled, or slandered, actually a chance to the Gegenoeffentlichkeit?Ist that not character assassination? Some years ago I am by coincidence the page " the Pranger " encountered, at that time ran not yet under the cover of the partner switching.Itself can individual persons, or communities of interests, from pure self purpose, such pages to serve, over under the cover of a doubtful Zivilkourage, through plot any rushing campaigns, own, quite persoehnliche interests to intersperse? Can such pages serve for the co-ordination of criminal machinations? The question, is it possibility or impossibility, technically and socially, individual persons, or also groupings of manipulating or of influencing from an criminal/ideological Energei, terrorizes or to schickanieren, directed.Target group manipulation by mass media are everyday manipulation, from which, more or less, can extract itself. Does the right to privatsphaere, creeping, by transmissions become deep psychological, how, for example " Big undermine brother"? If the Angemailten should be available a certain knowledge status to the topic with one, I would be glad over notes to the topic On the search for responses to my questions maile I different addresses from the Internet on, and hope up-constructional responses and criticisms.Over an attendance on the page wuerde I are pleased.If you should have been written down by me several times, then please I you to excuse me this that was not intended. The reason for my anonymity is the fact that with such Fragenstellerei, understandably, fast after the call the Psychatrie loud becomes. Which also method hat(ist). If you should feel the Mail as annoyance, I would like to apologize hereby for it! Big is watching you? Veuillez excuser le dérangement! Moi quelque chose concernant des oreilles est venu. Une cuisine de bruit relativement inhabituelle, dont on m'a placé un Sueppchen schwerverdauliches devant, est la raison de mes Mail.Aucune expression n'est peu appétissante! Il est possible sur un Wege(in funktechnischem pour quelles réponses fréquentielles?) quelqu'un influencer ou manipuler? Ou même schikanieren et terroriser? Sous le Motto:"Einen au Sender?Nich tout à fait seulement? Petits Mannim Ohr?Falsche Wellenlaenge?Bohnen dans les oreilles? Sur la dent gefuehlt(Amalgam)?Mal non contraignant reinhoeren? Le Pullacher Wanzentanz? Le Spinnerei?Das n'est-il quand même pas du tout va, ou? Et si comme cela paraît éthiquement moralement? Au côté technique de la chose, il y a certes des rapports et des Webseiten: Totalitaer,de - Die Waffe gegen die Kritik http://www.raum-und-zeit.com/Aktuell/Brummton.htm http://www.fosar-bludorf.com/Tempelhof/ http://jya.com/haarp.htm http://www.zeitenschrift.at/magazin/zs_24_15/1_mikrowaffen.htm http://www.bse-plus.de/d/doc/lbrief/lbmincontr.htm http://home.nexgo.de/kraven/bigb/big3.html http://w3.nrl.navy.mil/projects/haarp/index.html http://cryptome.org/ http://www.raven1.net/ravindex.htm http://www.calweb.com/~welsh/ http://www.cahe.org/ http://www.parascope.com/ds/mkultra0.htm http://www.trufax.org/menu/mind.html http://www.trufax.org/menu/elect.html http://mindcontrolforum.com/ http://www.trufax.org/menu/elect.html usw. usw. usw. toutefois qui ne peut quand même pas être qui on fait soetwas, ou? Une violation des droits de l'homme séparer ressembler!?! Il est possible, par la préparation, des oreilles et dans l'effet avec la prothèse dentaire éventuellement existante? Avec la technique de radio relativement simple?? Dans ce Land?Hier et aujourd'hui Sous quels motifs? Où le département est-il en réalité 5 du BND et de la protection d'constitution? peut il être qu'il y a les personnes qui livrent en permanence le BND/Verfassungsschutz, de manière funktechnischem un rapport de situation, sans le remarquer le -même , dans l'enfance rendu possible?? Par de tels collaborateurs officieux, avec le BND et la protection d'constitution, après manière, des informations sont-elles rassemblées et plus de, purement théoriquement, chaque citoyen allemand? Il y a alors encore un droit à des Privatsphere? Qui contrôle en réalité le BND, mad et protection d'constitution sur une infiltration??? Il s'agit en réalité dans le Mail me la question de savoir si lui éléments criminels, dont le motif de l'enrichissement, ou de groupements des motifs idéologiques, possible de s'acquérir le savoir et la technique qui à d'autres temps, est autre MotivenEt place-t-il le savoir technique dont le public vraiment la fin la barre de drapeau a connaissance ? Il n'est pas donc exactement la même chose possible pour des éléments criminels, moi cela maintenant fois verharmlost et minimisant une légende, personnes ou groupes particuliers avec des moyens relativement simples, de quels motifs aussi toujours, auszuspionieren?(Westfernsehen?), a été développé. Et ce "Ausspioniererei" ne représente-t-il pas une intervention considérable dans la vie privée? Il est possible personnes ou groupes particuliers, pour certain Oeffentlichkeit(suggeriert?), celui p. ex. à l'aide des côtés Internet, comme par exemple "le Pranger"geschaffen pourrait, fois vorausgestzt schikanieren terroriesieren et ou , et qui toute (suggerierten)Oeffentlichkeit?Haben les personnes ceux là, ou d'un autre côté verunglimpft, ou on ne pas calomnie, en réalité une chance au Gegenoeffentlichkeit?Ist qui meurtre d'appel? Il y a quelques années, je ne suis pas encore par hasard sur le côté "celui" poussé, fonctionnais alors cela sous la couche de pont de l'entremise partenaire. Des personnes particulières, ou des communautés d'intérêts le peuventelles, d'un autobut pur, de tels côtés servent, sous la couche de pont d'un Zivilkourage douteux, tracent plus de des campagnes de précipitation, propres intérêts tout à fait persoehnliche entremêlent? De tels côtés peuvent-ils servir à la coordination des manoeuvres criminelles? Question, est lui possibilité ou impossibilité de manipuler ou d'influencer techniquement et socialement, particulière personnes, ou aussi groupements, criminelle/ponctuel idéologique Energei dehors, , terroriser ou schickanieren, et ce.Une manipulation de groupe cible par des masse-médias être la manipulation quotidienne qui peut extraire mansich, plus ou moins. Le droit à la vie privée est-il miné, ramment, tiefenpsychologisch, par des envois, comme, par exemple "des Big brother"? Avec un les Angemailten si un certain savoir devait exister sur le thème, je serais heureux sur des indications sur le thème.Sur la recherche des réponses à mes questions je différentes adresses maile d'Internet dessus, et espère réponses et critiques aufkonstruktive. Sur une visite du côté http://hometown.aol.de/reinerhohn38259/homepage/index.html> je me réjouirais. Si vous deviez avoir été écrit à différentes reprises par moi, je vous demande de m'excuser cela qui n'était pas envisagé. La raison de mon anonymat est le fait qu'avec telle des Fragenstellerei, l'appel devient ce qui est bien compréhensible, rapidement bruyant après le Psychatrie. Ce que la méthode a également (ist). Si vous deviez ressentir les Mail comme un ennui, je voudrais m'excuser par ceci pour cela! Big brother is watching you? From grubert@users.sourceforge.net Mon Jun 3 08:35:37 2002 From: grubert@users.sourceforge.net (grubert@users.sourceforge.net) Date: Mon, 3 Jun 2002 09:35:37 +0200 (CEST) Subject: [Doc-SIG] ASCII to Word? In-Reply-To: <20020602203646.GA5174@panix.com> Message-ID: On Sun, 2 Jun 2002, Aahz wrote: > All right, I'm ready to get started on writing my book. My publisher > wants the document in Word format. I'm starting in some form of ASCII, > quite likely reST. What do people recommend as the best path for > getting from here to there? Is anyone else using reST for long > technical documents? > > In the absence of better advice, I'm going to convert to OpenOffice's > XML format, then use OpenOffice to convert to Word. One way or another, > I'm assuming that Python will be used for at least the first stage of > translation. > just for fun i started a try at a pdf writer, but have not really much time so if you really need a writer i might try to adapt or make a different one. for going to word html might be not a bad option as word would read it as i heard. what means word actually, a word readable format is definately something different ? would rtf be word enough ? -- BINGO: Think outside the box --- Engelbert Gruber -------+ SSG Fintl,Gruber,Lassnig / A6410 Telfs Untermarkt 9 / Tel. ++43-5262-64727 ----+ From guido@python.org Mon Jun 3 15:06:25 2002 From: guido@python.org (Guido van Rossum) Date: Mon, 03 Jun 2002 10:06:25 -0400 Subject: [Doc-SIG] ASCII to Word? In-Reply-To: Your message of "Mon, 03 Jun 2002 09:35:37 +0200." References: Message-ID: <200206031406.g53E6Pw00670@pcp742651pcs.reston01.va.comcast.net> > just for fun i started a try at a pdf writer, but have not really > much time so if you really need a writer i might try to adapt or > make a different one. Reportlab.com has an open source PDF writing library in Python. See http://Reportlab.com/opensource.html. --Guido van Rossum (home page: http://www.python.org/~guido/) From aahz@pythoncraft.com Mon Jun 3 17:36:17 2002 From: aahz@pythoncraft.com (Aahz) Date: Mon, 3 Jun 2002 12:36:17 -0400 Subject: [Doc-SIG] ASCII to Word? In-Reply-To: References: <20020602203646.GA5174@panix.com> Message-ID: <20020603163617.GB9703@panix.com> On Mon, Jun 03, 2002, grubert@users.sourceforge.net wrote: > On Sun, 2 Jun 2002, Aahz wrote: >> >> In the absence of better advice, I'm going to convert to OpenOffice's >> XML format, then use OpenOffice to convert to Word. One way or another, >> I'm assuming that Python will be used for at least the first stage of >> translation. > > just for fun i started a try at a pdf writer, but have not really much > time so if you really need a writer i might try to adapt or make a > different one. As Guido said, ReportLab has a PDF product; in fact, I use PythonPoint for my presentations (see my web page for examples). But I don't think that will help for getting to Word format. > for going to word html might be not a bad option as word would read > it as i heard. what means word actually, a word readable format is > definately something different ? would rtf be word enough ? RTF is an old format with few features; in particular, it doesn't support index tags. :-( I suspect HTML would have the same problem; I'll assume it does unless someone can tell me otherwise from direct experience. What I'd really like is a DocBook-to-Word converter, but I haven't seen anything like that. If I don't get anything here, my next step is to ask on comp.text.xml. -- Aahz (aahz@pythoncraft.com) <*> http://www.pythoncraft.com/ "In the end, outside of spy agencies, people are far too trusting and willing to help." --Ira Winkler From goodger@users.sourceforge.net Tue Jun 4 04:59:51 2002 From: goodger@users.sourceforge.net (David Goodger) Date: Mon, 03 Jun 2002 23:59:51 -0400 Subject: [Doc-SIG] ASCII to Word? In-Reply-To: <200206031406.g53E6Pw00670@pcp742651pcs.reston01.va.comcast.net> Message-ID: Engelbert Gruber wrote: >> just for fun i started a try at a pdf writer, but have not really >> much time so if you really need a writer i might try to adapt or >> make a different one. Guido van Rossum wrote: > Reportlab.com has an open source PDF writing library in Python. See > http://Reportlab.com/opensource.html. Engelbert's PDF writer for Docutils is an interface to ReportLab. -- David Goodger Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ From goodger@users.sourceforge.net Tue Jun 4 05:04:49 2002 From: goodger@users.sourceforge.net (David Goodger) Date: Tue, 04 Jun 2002 00:04:49 -0400 Subject: [Doc-SIG] ASCII to Word? In-Reply-To: <20020603163617.GB9703@panix.com> Message-ID: Aahz wrote: > All right, I'm ready to get started on writing my book. Great! What's the title and/or subject, if you can say? Are there any special features you'll need? > My publisher wants the document in Word format. My condolences. > I'm starting in some form of ASCII, quite likely reST. Glad to hear it. I (and hopefully others involved with Docutils) will be happy to help. But are there any other requirements other than "Word"? When I wrote a chapter on Python for Wrox [*]_, they sent me an elaborate (and broken) stylesheet to use. Anything like that? Could be significant. .. [*] *Professional Linux Programming*, chapter 15. My mug is at the far right, second from the top. Once you produce a Word document, I assume your publisher will add comments to the Word files and send them back to you for revision. (Wrox loved using Word's comment feature.) Will your publisher insist on preserving the comments and revision history? If they do insist on "read-write" Word files, you're screwed, and are stuck with Word. If they'll accept fresh, uncommented drafts each time, then using a toolchain to generate Word files as a final, read-only display format should be feasible. On second thought, I think you can merge versions of documents in Word, so you might be safe either way. > What do people recommend as the best path for getting from here to > there? My first thought on an interchange format would be RTF. I believe RTF can identify Word stylesheet styles by name, but I don't know it well. However: [Engelbert Gruber] >> for going to word html might be not a bad option as word would read >> it as i heard. what means word actually, a word readable format is >> definately something different ? would rtf be word enough ? [Aahz] > RTF is an old format with few features; in particular, it doesn't > support index tags. If anyone cares to dig in deep, the RTF 1.6 spec is online at: http://msdn.microsoft.com/library/?url=/library/en-us/dnrtfspec/html/rtfspec .asp The 1.7 spec can be downloaded from: http://download.microsoft.com/download/Word2002/Install/1.7/W98NT42KMeXP/EN- US/W2KRTFSF.exe > I suspect HTML would have the same problem; I'll assume it does > unless someone can tell me otherwise from direct experience. With the "class" attribute on "span" and "group" elements, HTML can represent literally anything, if indirectly and inelegantly. The problem is, can the software *reading* the HTML (Word, in this case) *do* anything with this information? Probably not. You'll need more direct access to native features. > Is anyone else using reST for long technical documents? Probably the longest existing documents in reStructuredText are those *describing* reStructuredText and Docutils: the specs and user docs. They're probably book-length in total. But I'm happy you're working to topple the record. > In the absence of better advice, I'm going to convert to > OpenOffice's XML format, then use OpenOffice to convert to Word. I found docs on the StarOffice XML spec (which is the draft for OpenOffice) at http://xml.openoffice.org/. It looks much more promising than RTF. If it's a reasonable markup -- and it appears to be so -- then I don't forsee any major problems with an "OpenOffice Writer" for Docutils. Any takers? > What I'd really like is a DocBook-to-Word converter, but I haven't > seen anything like that. If I don't get anything here, my next step > is to ask on comp.text.xml. I wouldn't be surprised if DocBook-to-Word converters *do* exist. The question then becomes, how to produce the DocBook? Would you still use reStructuredText? A "DocBook Writer" for Docutils shouldn't be too challenging. > One way or another, I'm assuming that Python will be used for at > least the first stage of translation. Just so long as you understand the current limitations, and you're realistic in your expectations. Docutils has a lot of growing and evolving yet to come. A lot of the support you need isn't in place yet. How much time will *you* be able to put in to the tools? If you're under serious deadline pressure, you may want to reconsider. Docutils is progressing, but only in people's spare time. Did that scare you off? If not, I'm sure that together we can come up with a decent system. Input from real-life usage like this is invaluable. Docutils will undoubtedly benefit. Please join the Docutils implementation mailing list: http://lists.sourceforge.net/lists/listinfo/docutils-develop/. Mostly, we discuss the nitty-gritties there, and high-level stuff here. -- David Goodger Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ From communityservices@racingknowledge.com Wed Jun 5 03:07:22 2002 From: communityservices@racingknowledge.com (communityservices@racingknowledge.com) Date: Tue, 04 Jun 2002 22:07:22 -0400 Subject: [Doc-SIG] WE NEED YOUR HELP Message-ID: <20020605001985.SM01128@127.0.0.1> Hello, Thank you for taking the time for reading this e-mail, my name is Michael Armstrong. I am founding member of Racing Knowledge (dot) Org [http://www.racingknowledge.org]. As some of you may now our former web site, although filled with information, was rather archaic. over the past three months the other founding members and myself have been working with a local development company to produce a new web site, this new web site will provide the following services for our members: Online Auctions Online Forums Racing News Racing Articles How To's Newsletters Track Locator Shop Locator Web Search (Specific to automotive needs) Post You Ride / Rate Your Ride We will also provide a place for shops, clubs and users to post a single page in our web directory of whatever they want (within reason). Racing Knowledge has always been and always will remain a free service. We do not and never intend to make any profit here, the only thing we ask is that our users click on our sponsors banners if they find a banner that interests them. HERE IS WHY WE NEED YOUR HELP Our former content was lost when our contract with our host expired this leaves us in a very sad position. What I ask of you is to help us get back to good with our new site that will be online within the next month or so, and even with the generic forum software in place of the old site now [http://www.racingknowledge.org], go there sign up post a question, get an answer. Browse our online store (we make no profit here, we make a commission of the sales and that helps pay the bills, this new site is costing us near 30,000 dollars that we are going to have to pay back over the next 3 months). Racing Knowledge T-shirts and Accessories: http://www.cafepress.com/cp/store/store.aspx?storeid=rko Racing Knowledge Store: http://racingknowledge.vstoreauto.com/ I am also looking for ad sponsors, forum moderators, and content. If you would like to write an article and have it posted on our site with your name and perhaps a banner of your choice to your web site, or anywhere you wish, please send it to content@racingknowledge.org Thank You For Your Time Michael Armstrong Founding Member Racing Knowledge marmstrong@racingknowledge.org http://www.racingknowledge.org From hefti@netcetera.ch Tue Jun 11 13:45:47 2002 From: hefti@netcetera.ch (Simon Hefti) Date: Tue, 11 Jun 2002 14:45:47 +0200 (MET DST) Subject: [Doc-SIG] docutils feedback Message-ID: Hi David, We discussed a couple of rst syntax fragments a couple of month ago. Now I actually started using docutils, and I like it. Here are a few questions and comments (I'm using docutils-0.1). - one problem resulted in this error message: Traceback (most recent call last): File "/home/hefti/local_in_archive/src/docutils-0.1/tools/html.py", line 26, in ? reporter=reporter) File "/usr/local/Python-2.2b1/lib/python2.2/site-packages/docutils/core.py", line 85, in publish pub.publish(source, destination) File "/usr/local/Python-2.2b1/lib/python2.2/site-packages/docutils/core.py", line 67, in publish self.writer.write(document, destination) File "/usr/local/Python-2.2b1/lib/python2.2/site-packages/docutils/writers/__init__.py", line 56, in write self.record() File "/usr/local/Python-2.2b1/lib/python2.2/site-packages/docutils/writers/html4css1.py", line 36, in record self.recordfile(self.output, self.destination) File "/usr/local/Python-2.2b1/lib/python2.2/site-packages/docutils/writers/__init__.py", line 86, in recordfile output = output.encode('raw-unicode-escape') # @@@ temporary UnicodeError: ASCII decoding error: ordinal not in range(128) ... where I wished to see the line number of the rst document more than the stack trace. In some error cases, the line number is shown, though. - just realized that the --version option is mssing: python html.py --version should, in my opinion, write some version info to stdout. - cannot handle umlauts ! I can see that you do not want to deal with exotic characters. I would expect docutils to be able to process a few standard character sets, though, including iso-8859-1. I'm a Tcl guy, where the programming language itself supports all kinds of encodings. I assume python can do this as well. - I'm not sure I like the table markup. I think that it is very usefull and complete, but perhaps sometimes a simpler variant could be helpful, e.g. like ---+----- id | desc ---+----- 1 | foo 2 | a rather long line which is not matched by the others ---+----- One problem I had was with a "...." in the table, which was interpreted as a title rather. I was confused because I was not thinking of writing titles within tables. Another problem of the table syntax is that monospaced chars are often not approriate to write complex tables (this is one reason why spread sheets are successfull), and long text in cells tends to blow the ASCII art up so much that it is not readable, or editable easily. - how to mark-up examples ? .. example:: would be nice - literal blocks: require no identation, please ! (but end-of-block) This was one of the main reasons for POD: start a document, copy-paste code or whatever, and process it into man pages, html and so forth. I would consider somthing like: previous para::my_end_tag select foo from bar where id=1; .. my_end_tag at least as a variant. - relative URLs ? I would like to add relative URLs, e.g.: see also /some/where/more.html Is there a mark-up for that ? Could docutils provide one ? Thanks a lot, Simon. ------------------------------------------------------------------------ Simon Hefti simon.hefti@netcetera.ch Netcetera AG, 8040 Zuerich phone +41 1 247 79 47 fax +41 1 247 70 75 From goodger@users.sourceforge.net Thu Jun 13 02:52:05 2002 From: goodger@users.sourceforge.net (David Goodger) Date: Wed, 12 Jun 2002 21:52:05 -0400 Subject: [Doc-SIG] docutils feedback In-Reply-To: Message-ID: Simon Hefti wrote: > - one problem resulted in this error message: > > Traceback (most recent call last): ... > File ".../docutils/writers/__init__.py", line 86, in recordfile > output = output.encode('raw-unicode-escape') # @@@ temporary > UnicodeError: ASCII decoding error: ordinal not in range(128) > > ... where I wished to see the line number of the rst document more > than the stack trace. In some error cases, the line number is shown, > though. This is a bug in the Docutils code, not a problem with the data, so it's appropriate to see a Python traceback. The code crashed! However, I believe the problem is solved in current CVS. Try installing from the CVS snapshot: http://docutils.sf.net/docutils-snapshot.tgz If the bug persists, please open a bug report on SourceForge, and include a minimal set of data and instructions to reproduce the error. > - just realized that the --version option is mssing: > python html.py --version > should, in my opinion, write some version info to stdout. If you're using the docutils-0.1 release, the front ends have no command line options *at all*. I've recently added a command-line interface to the front ends (install the CVS snapshot). By coincidence, I added a "--version" option just before I got your message. The changes will be checked in soon. I've been working on adding some features to Optik_ (which Docutils uses for command-line option processing), which is why Docutils has been quiet lately. .. _Optik: http://optik.sf.net/ > - cannot handle umlauts ! > > I can see that you do not want to deal with exotic characters. Docutils *does* want to deal with non-ASCII characters; it's on the to-do list (quite high-priority). Support for encodings just hasn't been implemented yet. I haven't needed it personally, and no one has stepped forward to implement it. I'd be happy for your help! > I'm a Tcl guy, where the programming language itself supports all > kinds of encodings. I assume python can do this as well. Yes, Python has very good Unicode & encoding support. I just don't understand it yet. And I'm not sure how best to implement such support for Docutils. > - I'm not sure I like the table markup. You're welcome to implement another! You have to realize, this is a volunteer open source project. Nobody is paying me to do any of this; telling me "I'm not sure I like the table markup" won't make me want to change it. You're welcome to implement new features; I encourage you to, and I'll be happy to help. If you do write some code, I hope you'll give it back to the project for everyone's benefit. There's a saying that's applicable to all open-source projects: If you want something done, hire someone -- if you want something done right, do it yourself. (John Jacob Astor) > I think that it is very usefull and complete, but perhaps > sometimes a simpler variant could be helpful, e.g. like > ---+----- > id | desc > ---+----- > 1 | foo > 2 | a rather long line which is not matched by the others > ---+----- I don't see that as significantly easier than the existing markup. See http://docutils.sf.net/spec/rst/problems.html#tables, alternative 2, for a much simpler syntax. Your idea of leaving the rightmost column unbounded may be useful (I remember you suggested this almost a year ago), but you need some way to indicate row separations. Using the syntax from alternative 2, slightly modified to incorporate your idea, your table could look like this:: == ==== id desc == ==== 1 foo -- ---- 2 a rather long line which is not matched by the others == ==== Using a directive, any (reasonable) syntax you like is feasible. You could implement a table where each line is assumed to be a row, or each entry in the first column implies a new row, or anything else. Here's another syntax idea, combining simple table syntax with bullet lists to indicate new rows, resulting in very simple and compact tables:: col 1 col 2 ===== ===== - 1 Second column of row 1. - 2 Second column of row 2. Second line of paragraph. - 3 Second column of row 3. Second paragraph of row 3, column 2 > One problem I had was with a "...." in the table, which was > interpreted as a title rather. I was confused because I was not > thinking of writing titles within tables. What is "...."? Are you thinking of ellipsis_? That's "..." (3 periods, not 4 [*]_), in English anyhow. The reStructuredText spec explicitly requires at least 4 repeated non-alphanumeric characters, "to avoid mistaking ellipses ["..."] for overlines". Do other languages use 4 periods to mean something significant? If so, I'll consider changing the spec & parser. Please provide an authoritative reference, online if possible. .. _ellipsis: http://webster.commnet.edu/grammar/marks/ellipsis.htm .. [*] Four periods *can* be seen at the end of a sentence: three ellipsis points plus the sentence-ending fullstop. However the ellipsis should be immediately adjacent to the final word; there should never be any space between the final word and the ellipsis, therefore the ellipsis cannot wrap to the next line and be misinterpreted as a title underline or overline. > Another problem of the table syntax is that monospaced chars are > often not approriate to write complex tables (this is one reason > why spread sheets are successfull), and long text in cells tends > to blow the ASCII art up so much that it is not readable, or > editable easily. So use a spreadsheet, or a word processor. reStructuredText is designed for plain text, which has limitations. We have to live with them. To write or read any kind of ASCII-art tables, a mononspaced typeface is a must. There's table-mode for emacs: http://table.sourceforge.net/. It doesn't support header row separators yet ("=" instead of "-"; any Elispers out there?). If you have another solution, I'd like to hear it. > - how to mark-up examples ? > > .. example:: would be nice This could be done. But what are the semantics? What is the behaviour? (What should the "example" directive *do*?) > - literal blocks: > > require no identation, please ! (but end-of-block) ... > I would consider somthing like: > > previous para::my_end_tag > > select foo from bar where id=1; > > .. my_end_tag > > at least as a variant. It would be easy enough to write a directive with semantics equivalent to the shell's "here-file" I/O redirection (e.g., ``command < This was one of the main reasons for POD: start a document, > copy-paste code or whatever, and process it into man pages, html > and so forth. I don't follow. Please explain. > - relative URLs ? > > I would like to add relative URLs, e.g.: > > see also /some/where/more.html > > Is there a mark-up for that ? Could docutils provide one ? There is no direct syntax now. You could re-code as:: see also more.html_. .. _more.html: /some/where/more.html Or you could use interpreted text with a "relative reference" role:: see also `/some/where/more.html`:rel: (Note: this is not implemented yet.) If you use it a lot, you could specify that "rel" is the default role for interpreted text in your documents. (Not implemented yet, either.) In conclusion, you have some interesting ideas, but most are not compelling enough for me to do anything with them any time soon. I'll put some of them on the to-do list. If you'd like to see something done about them in the short term, I welcome your participation. I'll be happy to help you to understand the inner workings of the code (and those discussions will contribute to the implementation docs). Thanks for the feedback, and I hope to see some code out of you! -- David Goodger Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ From hefti@netcetera.ch Thu Jun 13 07:01:34 2002 From: hefti@netcetera.ch (Simon Hefti) Date: Thu, 13 Jun 2002 08:01:34 +0200 (MET DST) Subject: [Doc-SIG] docutils feedback In-Reply-To: Message-ID: David, thanks for your comments. For now, I just a few responses: > You have to realize, this is a volunteer open source project. No worries. I'm aware of that. You asked for feedback, though ;) > > - how to mark-up examples ? > > > > .. example:: would be nice > > This could be done. But what are the semantics? What is the > behaviour? (What should the "example" directive *do*?) In the end, I will want to write rst, generate docbook out of it, and use whatever xsl is available/used/prescribed to convert if to the final format. So, I would like an example markup with the semantics similar to the docbook example tag: - callout (much like your ..note) - plus numbering/referencing - plus captions (both much like your .. figure) > > - literal blocks: > > This was one of the main reasons for POD POD is the perl plain old documentation. My use case is to write technical documentation, say a SQL cheat sheet. So I want show code and to explain it. Now, to be sure, I want to try out the code which is show. This is way I need copy/paste: I test in on some shell, copy it over to the doc (the rst file in that case), perhaps beautify/comment it, copy it back to the shell for testing and so forth. This is where the identation is in the way, and here docs would be handy. Simon. ------------------------------------------------------------------------ Simon Hefti simon.hefti@netcetera.ch Netcetera AG, 8040 Zuerich phone +41 1 247 79 47 fax +41 1 247 70 75 From aahz@pythoncraft.com Thu Jun 13 17:59:32 2002 From: aahz@pythoncraft.com (Aahz) Date: Thu, 13 Jun 2002 12:59:32 -0400 Subject: [Doc-SIG] docutils feedback In-Reply-To: References: Message-ID: <20020613165932.GA15360@panix.com> On Thu, Jun 13, 2002, Simon Hefti wrote: > > POD is the perl plain old documentation. My use case is to write > technical documentation, say a SQL cheat sheet. So I want show code > and to explain it. Now, to be sure, I want to try out the code which > is show. This is way I need copy/paste: I test in on some shell, copy > it over to the doc (the rst file in that case), perhaps > beautify/comment it, copy it back to the shell for testing and so > forth. This is where the identation is in the way, and here docs would > be handy. My solution to this problem has been to use an include directive -- no cut'n'paste required. I don't know how that will work in the reST world, though. -- Aahz (aahz@pythoncraft.com) <*> http://www.pythoncraft.com/ "I had lots of reasonable theories about children myself, until I had some." --Michael Rios From goodger@users.sourceforge.net Fri Jun 14 00:03:10 2002 From: goodger@users.sourceforge.net (David Goodger) Date: Thu, 13 Jun 2002 19:03:10 -0400 Subject: [Doc-SIG] docutils feedback In-Reply-To: <038e01c212b9$bb9466f0$545aa8c0@lslp862.int.lsl.co.uk> Message-ID: Simon, could you list Doc-SIG explicitly in the To: or Cc: field of your messages please? Tony's reply to your message didn't make it to the Doc-SIG, probably because he assumed that replying *to* a message which arrived *from* a mailing list would make it *back* to the mailing list. It should, but it didn't because of the non-standard headers in your message. I've quoted Tony's entire reply below for the benefit of the rest of Doc-SIG. [David] >> You have to realize, this is a volunteer open source project. [Simon] > No worries. I'm aware of that. You asked for feedback, though ;) Sure, and it's appreciated. The tone of your message was just a bit... demanding, that's all. I'll add your explanation of an "example" directive to the `to-do list`__. __ http://docutils.sf.net/spec/notes.html#body-example [Simon, re literal blocks and why he doesn't want them indented] > My use case is to write technical documentation, say a SQL cheat > sheet. So I want show code and to explain it. Now, to be sure, I > want to try out the code which is show. This is way I need > copy/paste: I test in on some shell, copy it over to the doc (the > rst file in that case), perhaps beautify/comment it, copy it back to > the shell for testing and so forth. This is where the identation is > in the way, and here docs would be handy. So your motivation is convenience. You want to avoid having to indent the interactive sessions you copy and paste into the docs in order to avoid having to unindent when you re-copy and paste the edited code for test purposes. Does that sum it up? I'm not going to change the syntax for literal blocks; indentation does a fine job IMO. Removing indentation as the delimiter would require block-end delimiters (there is already a block-start delimiter: "::"), which I am loathe to do. A directive like the "here-literal" example I showed seems like the best you'll get (although it's not very good!). But read on; perhaps the idea below will work for your SQL examples? [Tony's reply] > Hmm. There have been previous ideas on how to do this sort of thing. I think that "indented literal blocks" and "examples" are separate issues. In an "example", you'll still need syntax for the code or interactive session, to distinguish it from the explanatory text. > Minor digression > ---------------- > First off, we already have a "special case" for Python examples - the > support provided for blocks of Python code - for instance:: > > The following is targeted at doctest: > > >>> a = 1 > >>> a > 1 > > and can thus be used to test code... The point being, this syntax does *not* require indentation. The leading ">>> " prompt is sufficient to recognize the construct, and a blank line terminates the block. > (pysource, for instance, has a --doctest switch which allows it to > read a text file in and just pass it to doctest - intended for use > in writing some sorts of documentation/test script). Obviously this > special case is there for incestuous reasons - which is why this is > a minor digression. But... This gives me an idea. Perhaps we could generalize the "doctest block" construct (which is overly Python-centric) to other interactive sessions. "Doctest block" could be renamed to "I/O block" or "interactive block", and each of these could also be recognized as such by the parser: - Shell sessions:: $ cat example1.txt A block beginning with a "$ " prompt is interpreted as a shell session interactive block. As with Doctest blocks, the interactive block ends with the first blank line, and wouldn't have to be indented. - Root shell sessions:: # cat example2.txt A block beginning with a "# " prompt is interpreted as a root shell session (the user is or has to be logged in as root) interactive block. Again, the block ends with a blank line. Other standard (and unambiguous) interactive session prompts could easily be added. > Main point > ---------- > ...it's then not hard to envisage a directive that goes something like:: > > .. sqlcheat:: > explanation: > This is *not* real SQL! > sql: > FOR fred IN tables DO something; > > (apologies for what is doubtless poor directive layout design - > David is better at this sort of thing than I) which might: > > a. write out the explanation neatly > b. write out the SQL code neatly > c. *run* the SQL code and present the result > > (something similar was discussed at one point as a possible way of > allowing the reST quick reference to be written in reST - at the > moment it's hand-written in HTML). > > This approach has the major advantage of saving you all of that > manual cut-and-paste. It also means that if at some stage you want > to expand the examples to contrast what two different SQL > implementations do with the SQL code, you don't need to change the > text by much - just alter the explanation occasionally to reflect > that two sets of output are being produced. Instead, it's the > directive code that gets changed. So the advantage is that the running of the test code (embedded in the docs) is automated. All that's needed now is a clear set of requirements, a good design, and running code. ;-) -- David Goodger Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ From goodger@users.sourceforge.net Fri Jun 14 00:03:58 2002 From: goodger@users.sourceforge.net (David Goodger) Date: Thu, 13 Jun 2002 19:03:58 -0400 Subject: [Doc-SIG] docutils feedback In-Reply-To: <20020613165932.GA15360@panix.com> Message-ID: On Thu, Jun 13, 2002, Simon Hefti wrote: > My use case is to write technical documentation, say a SQL cheat > sheet. So I want show code and to explain it. Now, to be sure, I > want to try out the code which is show. Aahz wrote: > My solution to this problem has been to use an include directive -- > no cut'n'paste required. I don't know how that will work in the > reST world, though. It's on the to-do list, but hasn't been implemented yet: http://docutils.sf.net/spec/notes#misc-include. I'm not sure what semantics/behavior to apply though. Your solution seems to imply a context to the "include", such as "include a file, and interpret it as a literal block", but I'm not sure how best to specify the context. Worthy ideas; they require thought & discussion. Comments anyone? -- David Goodger Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ From aahz@pythoncraft.com Fri Jun 14 07:12:06 2002 From: aahz@pythoncraft.com (Aahz) Date: Fri, 14 Jun 2002 02:12:06 -0400 Subject: [Doc-SIG] docutils feedback In-Reply-To: References: <20020613165932.GA15360@panix.com> Message-ID: <20020614061206.GA28099@panix.com> > Aahz wrote: >> >> My solution to this problem has been to use an include directive -- >> no cut'n'paste required. I don't know how that will work in the >> reST world, though. > > It's on the to-do list, but hasn't been implemented yet: > http://docutils.sf.net/spec/notes#misc-include. I'm not sure what > semantics/behavior to apply though. Your solution seems to imply a > context to the "include", such as "include a file, and interpret it as > a literal block", but I'm not sure how best to specify the context. Seems to me that the simplest approach is to specify the context as a parameter to the include directive, or to create multiple include directives (one for each context one wishes to support). -- Aahz (aahz@pythoncraft.com) <*> http://www.pythoncraft.com/ "I had lots of reasonable theories about children myself, until I had some." --Michael Rios From tony@lsl.co.uk Fri Jun 14 12:19:25 2002 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Fri, 14 Jun 2002 12:19:25 +0100 Subject: [Doc-SIG] docutils feedback In-Reply-To: Message-ID: <039d01c21395$57847ab0$545aa8c0@lslp862.int.lsl.co.uk> David Goodger wrote: > Tony's reply to your message didn't make it to > the Doc-SIG, probably because he assumed that replying *to* a message > which arrived *from* a mailing list would make it *back* to the > mailing list. Drat - I *do* try to read the headers before hitting "send", but all too often I forget. > > (pysource, for instance, has a --doctest switch which allows it to > > read a text file in and just pass it to doctest - intended for use > > in writing some sorts of documentation/test script). Obviously this > > special case is there for incestuous reasons - which is why this is > > a minor digression. But... > > This gives me an idea. Perhaps we could generalize the "doctest > block" construct (which is overly Python-centric) to other interactive > sessions. "Doctest block" could be renamed to "I/O block" or > "interactive block", and each of these could also be recognized as > such by the parser: > > - Shell sessions:: > > $ cat example1.txt > A block beginning with a "$ " prompt is interpreted as a shell > session interactive block. As with Doctest blocks, the > interactive block ends with the first blank line, and wouldn't > have to be indented. > > - Root shell sessions:: > > # cat example2.txt > A block beginning with a "# " prompt is interpreted as a root > shell session (the user is or has to be logged in as root) > interactive block. Again, the block ends with a blank line. > > Other standard (and unambiguous) interactive session prompts could > easily be added. Hmm. I'd be against this, partly because it's multiplying entities ("now, is *this* particular format supported or not..."), partly because (for instance) my prompts don't look anything like the examples given (and your examples are very Unix-operating-system-centric), partly because that "(and unambiguous)" makes me uncomfortable, but mainly because this screams to me of a general solution presenting itself as specific instances, and thus the correct thing to do is to handle the general case. (common prompts I work with: * Unix: "lslsuj:tony > " * NT: "D:\LaserScan\java> " * our GIS product: "LULL> " so obviously, a block beginning with text containing a ">" should be special...) My gut feeling is that the sort of "example" directive I was discussing is probably the way to go for thinking about this sort of thing - and if it's a directive, we can leave it for later discussion as more experience is obtained. Of course, that leaves the ">>>" syntax for Python code as a special instance that could be argued as being out-of-place. Doesn't mean I want it to go away, though (and there is a patchwork-quilter's tradition, originating with the Amish, I believe, that no quilt should be perfect, because only God can make a perfect thing. So this can be our incorrect patch.). After all, it *is* a Python originated product, so some special support for Python might be expected. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From willg@bluesock.org Fri Jun 14 14:53:42 2002 From: willg@bluesock.org (will) Date: Fri, 14 Jun 2002 08:53:42 -0500 (CDT) Subject: [Doc-SIG] docutils feedback In-Reply-To: <039d01c21395$57847ab0$545aa8c0@lslp862.int.lsl.co.uk> Message-ID: On Fri, 14 Jun 2002, Tony J Ibbs (Tibs) wrote: > > Of course, that leaves the ">>>" syntax for Python code as a special > instance that could be argued as being out-of-place. Doesn't mean I want > it to go away, though (and there is a patchwork-quilter's tradition, > originating with the Amish, I believe, that no quilt should be perfect, > because only God can make a perfect thing. So this can be our incorrect > patch.). After all, it *is* a Python originated product, so some special > support for Python might be expected. I think this is a myth in regards to Amish patchwork quilting. However, it is true of Persian rugs--they're always made with slight and minor irregularities due to the belief that God is the only ultimate perfect being and we shouldn't be attempting something perfect because that would be like claiming the position of the almighty. That would be bad. I think if we have the choice, I'd rather we didn't explicitly put flaws in the reST syntax for the sole purpose of not insulting the almighty. Course, it's not like creating a readable ascii formatting syntax is as easy as making apple pie. So I don't really think we're in danger of that sort of thing. :) /will From delza@mac.com Fri Jun 14 18:19:12 2002 From: delza@mac.com (Dethe Elza) Date: 14 Jun 2002 10:19:12 -0700 Subject: [Doc-SIG] Docbook output Message-ID: <1024075153.860.6.camel@laptop> Hi folks, Has any work been done to create DocBook output from reST input? If not, where would I begin if I wanted to tackle such a thing? I'm actually interested in three output formats (in addition to XHTML and PDF, which appear to be well in hand): * DocBook * Simplified DocBook * XMLspec (the format W3C docs are written in) If there's anyone working on this already, how can I help? Please cc any reply, as I'm not (yet?) a subscriber to the list. TIA -Dethe From oliver@rutherfurd.net Fri Jun 14 23:11:15 2002 From: oliver@rutherfurd.net (Oliver Rutherfurd) Date: Fri, 14 Jun 2002 17:11:15 -0500 Subject: [Doc-SIG] Docbook output In-Reply-To: <1024075153.860.6.camel@laptop> References: <1024075153.860.6.camel@laptop> Message-ID: <20020614221115.GA30564@urfe.newtonsplace.net> On Fri, Jun 14, 2002 at 10:19:12AM -0700, Dethe Elza wrote: > Hi folks, > > Has any work been done to create DocBook output from reST input? If > not, where would I begin if I wanted to tackle such a thing? Hi, I just started on a docbook writer yesterday evening. It's probably about 1/4 done (but I started with all the easy elements ;-). I've never really used DocBook before, so I'm not very familiar with it, but I'm just trying to use the html writer as an example, and going from there. One question I had was what type of document(s) to generate? - book - chapter - article It would be nice if all 3 could be generated based on a parameter given to the writer, but given my lack of experience w/DocBook I don't know if this is feasible. Anyway, if I don't stall out or hit any big roadblocks, I'll try to make something available later this weekend. -Ollie > I'm actually interested in three output formats (in addition to XHTML > and PDF, which appear to be well in hand): > > * DocBook > * Simplified DocBook > * XMLspec (the format W3C docs are written in) > > If there's anyone working on this already, how can I help? > > Please cc any reply, as I'm not (yet?) a subscriber to the list. > > TIA > > -Dethe > > > > _______________________________________________ > Doc-SIG maillist - Doc-SIG@python.org > http://mail.python.org/mailman/listinfo/doc-sig > > From goodger@users.sourceforge.net Sat Jun 15 00:13:56 2002 From: goodger@users.sourceforge.net (David Goodger) Date: Fri, 14 Jun 2002 19:13:56 -0400 Subject: [Doc-SIG] docutils feedback In-Reply-To: <039d01c21395$57847ab0$545aa8c0@lslp862.int.lsl.co.uk> Message-ID: > David Goodger wrote: >> This gives me an idea. Perhaps we could generalize the "doctest >> block" construct (which is overly Python-centric) to other >> interactive sessions. Tony J Ibbs (Tibs) wrote: > Hmm. I'd be against this, Tony, ever the voice of restraint ;->. A useful role, actually. Taking your points out of order: > partly because (for instance) my prompts don't look anything like > the examples given (and your examples are very > Unix-operating-system-centric), ... > (common prompts I work with: > > * Unix: "lslsuj:tony > " > * NT: "D:\LaserScan\java> " > * our GIS product: "LULL> " > > so obviously, a block beginning with text containing > a ">" should be special...) A "> " WinDOS prompt would be feasible. Your Unix prompt is *decidedly* non-standard though. > partly because that "(and unambiguous)" makes me uncomfortable, Why? > partly because it's multiplying entities ("now, is *this* particular > format supported or not..."), ... > but mainly because this screams to me of a general solution > presenting itself as specific instances, and thus the correct thing > to do is to handle the general case. I thought it *was* addressing the general case, admittedly with a limited set of examples. The real world is a varied place, and many solutions have to be piecemeal by necessity. > My gut feeling is that the sort of "example" directive I was > discussing is probably the way to go for thinking about this sort of > thing - and if it's a directive, we can leave it for later > discussion as more experience is obtained. The "interactive block" I proposed wasn't addressing the "example" directive, rather Simon Hefti's objection to indented literal blocks. But I agree that the solution (or even the *need* for a solution) isn't clear. I don't really see the need myself. For now, I've added the "interactive block" idea to the to-do list (with a "?"). It will languish there until a champion claims it. -- David Goodger Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ From goodger@users.sourceforge.net Sat Jun 15 00:25:43 2002 From: goodger@users.sourceforge.net (David Goodger) Date: Fri, 14 Jun 2002 19:25:43 -0400 Subject: [Doc-SIG] Docbook output In-Reply-To: <20020614221115.GA30564@urfe.newtonsplace.net> Message-ID: Dethe Elza wrote: > Has any work been done to create DocBook output from reST input? I don't think so. Welcome! > If not, where would I begin if I wanted to tackle such a thing? First, make sure you're using the latest Docutils from CVS. Either get the files directly from CVS (instructions here: http://sourceforge.net/cvs/?group_id=38414), or get the latest snapshot (http://docutils.sourceforge.net/docutils-snapshot.tgz). Second, take a look at docutils/writers/html4css1.py, which is the only complete output writer so far. It uses the "Visitor" design pattern to do walk the document tree. Third, join the Docutils-specific mailing lists: - docutils-develop, for implementation discussions: http://lists.sf.net/lists/listinfo/docutils-develop/ - docutils-checkins, for CVS checkin messages (normally read-only): http://lists.sf.net/lists/listinfo/docutils-checkins/ (Join Doc-SIG too; high-level discussions take place here.) Finally, ask lots of questions. The internals are not well documented yet; your questions will help to fill the gaps. > I'm actually interested in three output formats ... : > > * DocBook > * Simplified DocBook > * XMLspec (the format W3C docs are written in) Great! I know DocBook quite well (as do many others, I'm sure), so we will be able to help conceptually map Docutils nodes to DocBook elements. It should be easy. I don't know anything about XMLspec. > (in addition to XHTML and PDF, which appear to be well in hand) Englebert Gruber began work on PDF (via ReportLabs), but it still needs a lot of work. Englebert, what are your plans? Oliver Rutherfurd wrote: > I just started on a docbook writer yesterday evening. ... > Anyway, if I don't stall out or hit any big roadblocks, I'll try to > make something available later this weekend. That's great! I look forward to seeing it. Let us know if you run into any trouble. I'll be checking mail over the weekend. And welcome! > One question I had was what type of document(s) to generate? > > - book > - chapter > - article > > It would be nice if all 3 could be generated based on a parameter > given to the writer, but given my lack of experience w/DocBook I > don't know if this is feasible. You could add command-line options to choose the top-level element of the DocBook output. Articles and chapters contain sections, and books contain chapters. But I wouldn't worry about it for now. Choose one (article seems best); we can add bells & whistles later. -- David Goodger Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ From goodger@users.sourceforge.net Sun Jun 16 04:30:33 2002 From: goodger@users.sourceforge.net (David Goodger) Date: Sat, 15 Jun 2002 23:30:33 -0400 Subject: [Doc-SIG] Docbook output In-Reply-To: Message-ID: > ... where would I begin if I wanted to tackle such a thing? I forgot to mention was that you should also look at: - spec/docutils.dtd: This is the authority on the standard Docutils elements and their relationships. It may give you some clues about the semantics of Docutils document tree nodes. - "Project Policies" in spec/notes.txt: This is an overview of how the Docutils project is set up, and some guidelines that will help make development go smoothly. (Also online at http://docutils.sf.net/spec/notes.html#project-policies) As always, feedback is welcome. -- David Goodger Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ From delza@mac.com Sun Jun 16 05:56:31 2002 From: delza@mac.com (Dethe Elza) Date: Sat, 15 Jun 2002 21:56:31 -0700 Subject: [Doc-SIG] Docbook output In-Reply-To: Message-ID: <6D0F15EE-80E5-11D6-979B-003065CA8E18@mac.com> OK, thanks for the feedback. For reference, Simplified Docbook (current draft) is at: http://www.oasis-open.org/docbook/xml/simple/1.0CR1/index.shtml The DTD is specifically aimed at documents with root
. And the XMLspec info is at: http://www.w3.org/XML/1998/06/xmlspec-report-v21.htm I've done a bit more of my homework and read through the HTML writer, which looks clear enough. Sometimes I forget how easy it is to read the source in Python. Of course, it helps when the project is well-organized. Kudos to you. I've also joined the mailing lists, will load from CVS later. Thanks and I hope to be of some help. --Dethe -- "Melting down holy grails to make silver bullets for my .357 Panacea" Dethe Elza (delza@burningtiger.com) Chief Mad Scientist Enfolding Systems (http://enfoldingsystems.com) Weblog: http://livingcode.ca/ From bert@chello.at Sun Jun 16 13:53:15 2002 From: bert@chello.at (engelbert gruber) Date: Sun, 16 Jun 2002 14:53:15 +0200 (CEST) Subject: [Doc-SIG] docutils feedback In-Reply-To: Message-ID: subject should say : code innclusion anyone ever thought about support for literate programming. e.g. -------- to start up the program enter <>= bash @ and then type <>= exit @ to leave. ------ indentation does not mind as one should extract/tangle the code and could cut an paste from the file sample.script (i think it is a no web feature, that top chunks that contain no blanks are written to files). -- engelbert gruber email: engelbert.gruber@ssg.co.at From guido@python.org Sun Jun 16 15:06:49 2002 From: guido@python.org (Guido van Rossum) Date: Sun, 16 Jun 2002 10:06:49 -0400 Subject: [Doc-SIG] docutils feedback In-Reply-To: Your message of "Sun, 16 Jun 2002 14:53:15 +0200." References: Message-ID: <200206161406.g5GE6nw32333@pcp02138704pcs.reston01.va.comcast.net> > anyone ever thought about support for literate programming. For literate programming support, see Leo: http://sourceforge.net/projects/leo/ --Guido van Rossum (home page: http://www.python.org/~guido/) From lennon@day-reynolds.com Sun Jun 16 19:21:44 2002 From: lennon@day-reynolds.com (Lennon Day-Reynolds) Date: Sun, 16 Jun 2002 11:21:44 -0700 Subject: [Doc-SIG] Docbook output In-Reply-To: <6D0F15EE-80E5-11D6-979B-003065CA8E18@mac.com> Message-ID: I've been lurking here for quite a while, but thought I would weigh in quickly on the issue of DocBook output, since I spent a good portion of the last year working with about a dozen developers creating a DocBook-based documentation system for a research programming and specification language. We experimented with "custom" markup syntaxes, automatic DocBook generation from source code, etc., and the experience was not as pleasant or fruitful as I had initially hoped. Basically, DocBook is the 400-lb. gorilla of markup formats. Most of our developers never used more than a 12-25 of the several hundred available element types, simply because there were too many to remember the proper nesting and attribute declaration policies for. The semantic richness of fully "DocBook-ized" documentation is impressive, but the time involved in actually placing more than basic structural and keyword markup around the text proved prohibitive in most cases. WRT to the choice of top-level element ('book', 'chapter', 'article', et. al.), I would have to recommend starting with the Simplified DTD, unless you're going to allow some sort of inline directive in the source to make the chapter, section, and appendix blocks explicit. Of course, you could just create one "default" template which included a "global" foreword, and then had chapters assigned to each source file in the original document, but it seems like an awful lot of work just for something that's usually intended to be an precursor format for HTML, PDF, or LaTeX final output. If you're seriously committed to DocBook output, though, might it not be easier to simply use an XSLT stylesheet to convert the DocUtils "native" XML format (basically just a dump of the internal document node structure, IIRC) into DocBook, rather than a seperate Python implementation? I'm a die-hard Python user, as well, but XSLT really is a great tool for this kind of deep tree walking and transformation task, esp. when your input and output are already both going to be XML documents. One specific "gotcha" to keep an eye out for: DocBook tables are painful, compared to HTML. Web browsers, and even other document publishing tools, are pretty good about making a "best guess" attempt at laying out simple tables according to their contents, with little or no explicit size information from the author, but most of the DocBook rendering tools I've used tend to mangle any table that doesn't include explicit column widths. In short, personally, I don't see any real use to DocBook output if HTML and PDF are already available with any degree of customizable formatting. Of course, that doesn't exclude the possibility that you might really want/need DocBook and XMLspec. So, now that I've done my soapboxing for the day, it's time for some breakfast. Good luck, either way. Lennon Day-Reynolds P.S.: To everyone who's contributed to the Doc-SIG, reST, etc., I say, "Good work!" Things are starting to look really good, guys and gals. On Saturday, June 15, 2002, at 09:56 PM, Dethe Elza wrote: > OK, thanks for the feedback. > > For reference, Simplified Docbook (current draft) is at: > http://www.oasis-open.org/docbook/xml/simple/1.0CR1/index.shtml > The DTD is specifically aimed at documents with root
. > > And the XMLspec info is at: > http://www.w3.org/XML/1998/06/xmlspec-report-v21.htm > > I've done a bit more of my homework and read through the HTML writer, > which looks clear enough. Sometimes I forget how easy it is to read > the source in Python. Of course, it helps when the project is > well-organized. Kudos to you. > > I've also joined the mailing lists, will load from CVS later. > > Thanks and I hope to be of some help. > > --Dethe > > -- > "Melting down holy grails to make silver bullets for my .357 Panacea" > Dethe Elza (delza@burningtiger.com) > Chief Mad Scientist > Enfolding Systems (http://enfoldingsystems.com) > Weblog: http://livingcode.ca/ > > > > _______________________________________________ > Doc-SIG maillist - Doc-SIG@python.org > http://mail.python.org/mailman/listinfo/doc-sig > > Lennon Day-Reynolds mail: lennon@day-reynolds.com www: http://day-reynolds.com/lennon/ From grubert@users.sourceforge.net Mon Jun 17 12:49:57 2002 From: grubert@users.sourceforge.net (grubert@users.sourceforge.net) Date: Mon, 17 Jun 2002 13:49:57 +0200 (CEST) Subject: [Doc-SIG] Docbook output In-Reply-To: <1024075153.860.6.camel@laptop> Message-ID: On 14 Jun 2002, Dethe Elza wrote: > Hi folks, > > Has any work been done to create DocBook output from reST input? If > not, where would I begin if I wanted to tackle such a thing? > > I'm actually interested in three output formats (in addition to XHTML > and PDF, which appear to be well in hand): you nearly got the point it is not my hand it is the elbow that is broken, similar to my pdf-writer :-) > -- BINGO: change the basis of competition --- Engelbert Gruber -------+ SSG Fintl,Gruber,Lassnig / A6410 Telfs Untermarkt 9 / Tel. ++43-5262-64727 ----+ From Ueli.Schlaepfer@esec.com Mon Jun 17 17:48:03 2002 From: Ueli.Schlaepfer@esec.com (Schlaepfer, Ueli (ESEC ZG)) Date: Mon, 17 Jun 2002 18:48:03 +0200 Subject: [Doc-SIG] Non-ASCII Characters in reST (was: [Doc-SIG] docutils f eedback ) Message-ID: <2DB8BE7586F3D411B94F0008C786D940CF1AE6@eseczg22.e041zg02.esec.com> Hi all, In a recent thread, Simon posted the following traceback:: Traceback (most recent call last): File "/home/hefti/local_in_archive/src/docutils-0.1/tools/html.py", = line 26, in ? reporter=3Dreporter) File "/usr/local/Python-2.2b1/lib/python2.2/site-packages/docutils/core.py", = line 85, in publish pub.publish(source, destination) File "/usr/local/Python-2.2b1/lib/python2.2/site-packages/docutils/core.py", = line 67, in publish self.writer.write(document, destination) File "/usr/local/Python-2.2b1/lib/python2.2/site-packages/docutils/writers/__= init __.py", line 56, in write self.record() File "/usr/local/Python-2.2b1/lib/python2.2/site-packages/docutils/writers/ht= ml4c ss1.py", line 36, in record self.recordfile(self.output, self.destination) File "/usr/local/Python-2.2b1/lib/python2.2/site-packages/docutils/writers/__= init __.py", line 86, in recordfile output =3D output.encode('raw-unicode-escape') # @@@ temporary UnicodeError: ASCII decoding error: ordinal not in range(128) =09 To which David replied: >> This is a bug in the Docutils code, not a problem with the data, = so >> it's appropriate to see a Python traceback. The code crashed! >>=20 >> However, I believe the problem is solved in current CVS. Try >> installing from the CVS snapshot: >> http://docutils.sf.net/docutils-snapshot.tgz I ran into this bug before (I happen to have an '=E4' in my last name, = so it occured at least once per document) and tracked it to line 98 = in docutils/writers/__init__.py, which reads (note the ``temporary``!):: output =3D output.encode('utf-8') # @@@ temporary; must not hard-code Apparently, ``'something'.encode()`` expects ``'something'`` to = contain clean 7-bit ASCII text. My quick-and-dirty fix to the problem was = to comment out this line. The offending chjaracters make it through to = the HTML, but as my documents are for internal use only, this doesn't = matter so far. Now I just checked with yesterdays (june 16) CVS. The = `minimal document`_ below still triggers the bug, contrary to David's statement. .. _`minimal document`: =3D=3D=3D 8< = =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =E4 =3D=3D=3D 8< = =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D ;-) Fixing this kind of things can be nasty, I think -- for a simple = text file, there's (AFAIK) no way to know the encoding but guessing. = It's the raison d'=EAtre for TeX's "inputenc" package (and for a few = more, I think). This package provides a way to state the encoding in the = source file. One way to handle it would probably be to have such an educated = guess based on the system docutils is running on (assuming the file was = typed in a dumb editor on the same machine), and to allow the encoding to = be stated explicitly with a directive along the lines:: .. encoding: cp1250 That's it for now... (I was hoping to provide a fix, but my current = work situation doesn't allow for substantial contributions :-( ) --=20 Ueli From goodger@users.sourceforge.net Tue Jun 18 03:27:29 2002 From: goodger@users.sourceforge.net (David Goodger) Date: Mon, 17 Jun 2002 22:27:29 -0400 Subject: [Doc-SIG] Non-ASCII Characters in reST (was: [Doc-SIG] docutils f eedback ) In-Reply-To: <2DB8BE7586F3D411B94F0008C786D940CF1AE6@eseczg22.e041zg02.esec.com> Message-ID: Ueli Schlaepfer wrote: > In a recent thread, Simon posted the following traceback:: >=20 > Traceback (most recent call last): ... > "...docutils/writers/__init__.py", line 86, in recordfile > output =3D output.encode('raw-unicode-escape') # @@@ temporary > UnicodeError: ASCII decoding error: ordinal not in range(128) > =20 > To which David replied: >=20 > >> This is a bug in the Docutils code, not a problem with the data, > >> so it's appropriate to see a Python traceback. The code crashed! > >>=20 > >> However, I believe the problem is solved in current CVS. Try > >> installing from the CVS snapshot: > >> http://docutils.sf.net/docutils-snapshot.tgz ... > Now I just checked with yesterdays (june 16) CVS. The `minimal > document`_ below still triggers the bug, contrary to David's > statement. This is an input encoding issue, the solution to which (you guessed it!) hasn't been implemented yet. I'm not even sure what the solution should be. Although I've worked with different "character sets" in the past (such as Japanese SJIS, and Chinese and Korean encodings), the encoding was always known beforehand. With Docutils, it won't be. Anyone with Unicode encoding/decoding experience, I'd appreciate some advice. I've got an "--encoding" option in docutils/frontend.py, but it's commented out as unimplemented. I've heard that such a command-line option is a **bad thing**, as are inline magic comments or directives. There's a comment, "Take default encoding & language from locale?". I don't know how best to proceed. I'd like to make the *right* decision here, not just "good enough for now". That's one of the reasons I haven't implemented the encoding issue yet. I've seen this debated, on Python-Dev and elsewhere, but I have yet to be shown "the one true way" or convinced that it *is* the right way. Another reason is because there are really two encodings at play here: the input encoding and the output encoding. Is it reasonable to require that both be specified (with UTF-8 as defaults)? Western Europeans will want to use Latin-1 as the default, but that's not friendly to the rest of the world. Is locale the answer? Or are explicit command-line options the best way? A combination? My brain hurts. > I ran into this bug before (I happen to have an '=E4' in my last name, > so it occured at least once per document) and tracked it to line 98 > in docutils/writers/__init__.py, which reads (note the > ``temporary``!):: >=20 > output =3D output.encode('utf-8') # @@@ temporary; must not hard-code >=20 > Apparently, ``'something'.encode()`` expects ``'something'`` to > contain clean 7-bit ASCII text. My understanding is as follows (please correct me if I'm wrong). ``output.encode('utf-8')`` actually expects ``output`` to be a Unicode string, *not* 7-bit ASCII. If it's a regular (8-bit, non-Unicode) string, the operation will try to coerce it (decode it using the default encoding) into a Unicode string, then encode that into a UTF-8-encoded 8-bit string. It's the *decoding* stage that's raising the exception, because the default encoding is 7-bit "ascii", and ``output`` is a regular string containing non-ASCII (the a+umlaut). As an experiment, could you try editing your site.py file? Try enabling the locale-detecting mechanism (search for "locale"), and/or the explicit default encoding above it. What happens then? > My quick-and-dirty fix to the problem was to comment out this line. > The offending chjaracters make it through to the HTML, but as my > documents are for internal use only, this doesn't matter so far. As I said, the problem isn't encoding the output, it's decoding the input. Since the HTML being produced says it's using UTF-8, if there are non-ASCII charactes in your output they may be misinterpreted by your browser. > Fixing this kind of things can be nasty, I think -- for a simple > text file, there's (AFAIK) no way to know the encoding but guessing. Yes. The question is, how best to guess? And how best to override the guesswork? > One way to handle it would probably be to have such an educated > guess based on the system docutils is running on (assuming the file > was typed in a dumb editor on the same machine), and to allow the > encoding to be stated explicitly with a directive along the lines:: >=20 > .. encoding: cp1250 That's an alternative (already in the "To Do" list). It's not my favorite, since it's ugly and can lie. When saving from a text editor a file could be re-encoded without the author noticing, and the "encoding" directive would become wrong. --=20 David Goodger Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ From aahz@pythoncraft.com Tue Jun 18 03:36:14 2002 From: aahz@pythoncraft.com (Aahz) Date: Mon, 17 Jun 2002 22:36:14 -0400 Subject: [Doc-SIG] Non-ASCII Characters in reST (was: [Doc-SIG] docutils f eedback ) In-Reply-To: References: <2DB8BE7586F3D411B94F0008C786D940CF1AE6@eseczg22.e041zg02.esec.com> Message-ID: <20020618023614.GA28362@panix.com> On Mon, Jun 17, 2002, David Goodger wrote: > > I've got an "--encoding" option in docutils/frontend.py, but it's > commented out as unimplemented. I've heard that such a command-line > option is a **bad thing**, as are inline magic comments or directives. > There's a comment, "Take default encoding & language from locale?". I > don't know how best to proceed. I'd like to make the *right* decision > here, not just "good enough for now". That's one of the reasons I > haven't implemented the encoding issue yet. I've seen this debated, > on Python-Dev and elsewhere, but I have yet to be shown "the one true > way" or convinced that it *is* the right way. See PEP 263. That way, at worst you're compatible with Python. > Another reason is because there are really two encodings at play here: > the input encoding and the output encoding. Is it reasonable to > require that both be specified (with UTF-8 as defaults)? Western > Europeans will want to use Latin-1 as the default, but that's not > friendly to the rest of the world. Is locale the answer? Or are > explicit command-line options the best way? A combination? I'd suggest a directive as the answer to output encoding; someone who wants to implement dynamic output encoding can do so with an extension directive of some kind. Just make the API clear. -- Aahz (aahz@pythoncraft.com) <*> http://www.pythoncraft.com/ Project Vote Smart: http://www.vote-smart.org/ From goodger@users.sourceforge.net Tue Jun 18 04:16:04 2002 From: goodger@users.sourceforge.net (David Goodger) Date: Mon, 17 Jun 2002 23:16:04 -0400 Subject: [Doc-SIG] Non-ASCII Characters in reST (was: [Doc-SIG] docutils f eedback ) In-Reply-To: <20020618023614.GA28362@panix.com> Message-ID: > On Mon, Jun 17, 2002, David Goodger wrote: >> I've got an "--encoding" option in docutils/frontend.py, but it's >> commented out as unimplemented. I've heard that such a command-line >> option is a **bad thing**, as are inline magic comments or directives. >> There's a comment, "Take default encoding & language from locale?". I >> don't know how best to proceed. I'd like to make the *right* decision >> here, not just "good enough for now". That's one of the reasons I >> haven't implemented the encoding issue yet. I've seen this debated, >> on Python-Dev and elsewhere, but I have yet to be shown "the one true >> way" or convinced that it *is* the right way. Aahz wrote: > See PEP 263. That way, at worst you're compatible with Python. That's what I'm talking about; I'm not convinced by PEP 263. I have strong reservations about the magic comment it proposes. I hesitate to add similar recognition logic to Docutils/reStructuredText. I'm no expert, but it seems flawed somehow. It could very well be the best solution, but it doesn't seem that way to me. Does anybody know of any good, authoritative references on the subject? -- David Goodger Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ From Ueli.Schlaepfer@esec.com Tue Jun 18 08:00:13 2002 From: Ueli.Schlaepfer@esec.com (Schlaepfer, Ueli (ESEC ZG)) Date: Tue, 18 Jun 2002 09:00:13 +0200 Subject: [Doc-SIG] Non-ASCII Characters in reST (was: [Doc-SIG] docuti ls f eedback ) Message-ID: <2DB8BE7586F3D411B94F0008C786D940CF1AE7@eseczg22.e041zg02.esec.com> Hi again, > David Goodger wrote: [...] > This is an input encoding issue, the solution to which (you guessed > it!) hasn't been implemented yet. I'm not even sure what the = solution > should be. Although I've worked with different "character sets" in > the past (such as Japanese SJIS, and Chinese and Korean encodings), > the encoding was always known beforehand. With Docutils, it won't = be. > Anyone with Unicode encoding/decoding experience, I'd appreciate some > advice. Emacs does some guesswork concerning file encoding -- should we have = a look at that for a starter? > I've got an "--encoding" option in docutils/frontend.py, but it's > commented out as unimplemented. I've heard that such a command-line > option is a **bad thing**, as are inline magic comments or = directives. > There's a comment, "Take default encoding & language from locale?". = I > don't know how best to proceed. I'd like to make the *right* = decision > here, not just "good enough for now". That's one of the reasons I > haven't implemented the encoding issue yet. I've seen this debated, > on Python-Dev and elsewhere, but I have yet to be shown "the one true > way" or convinced that it *is* the right way. I'm way off base here, but as I mentioned -- one condition is that = the result is not "anything-centric", but defaults to a reasonable = value. If the locale is wrong -- well, blame the site administrator... The language is much less of an issue, I think. Stating it in = the document if it's not what the default would be is easy enough = to understand, and such a statement won't turn into a lie as easily as = the encoding. A command-line option is a must, though; I don't expect = an American to state that his documents are in English, but I won't = state it if mine are in German either. So I need a way to tell the = frontend what language it should use. > Another reason is because there are really two encodings at play = here: > the input encoding and the output encoding. Is it reasonable to > require that both be specified (with UTF-8 as defaults)? Western > Europeans will want to use Latin-1 as the default, but that's not > friendly to the rest of the world. Is locale the answer? Or are > explicit command-line options the best way? A combination? A sensible default is definitely required. Explicit command or = another mechanism should be there, too, but as a last resort only and for = people who (unlike me ;-) know what they're doing. > My brain hurts. > > > I ran into this bug before (I happen to have an '=E4' in my last = name, > > so it occured at least once per document) and tracked it to line 98 > > in docutils/writers/__init__.py, which reads (note the > > ``temporary``!):: > >=20 > > output =3D output.encode('utf-8') # @@@ temporary; must not = hard-code > >=20 > > Apparently, ``'something'.encode()`` expects ``'something'`` to > > contain clean 7-bit ASCII text. > > My understanding is as follows (please correct me if I'm wrong). > ``output.encode('utf-8')`` actually expects ``output`` to be a = Unicode > string, *not* 7-bit ASCII. If it's a regular (8-bit, non-Unicode) > string, the operation will try to coerce it (decode it using the > default encoding) into a Unicode string, then encode that into a > UTF-8-encoded 8-bit string. It's the *decoding* stage that's raising > the exception, because the default encoding is 7-bit "ascii", and > ``output`` is a regular string containing non-ASCII (the a+umlaut). > As an experiment, could you try editing your site.py file? Try > enabling the locale-detecting mechanism (search for "locale"), and/or > the explicit default encoding above it. What happens then? Thanks for the clarification! The experiment you suggested = suggests that you're correct. I just tried enabling locale detection, and = the error went away... My fix is a lot less dirty now :-) > As I said, the problem isn't encoding the output, it's decoding the > input. Since the HTML being produced says it's using UTF-8, if there > are non-ASCII charactes in your output they may be misinterpreted by > your browser. I'm aware of that. But since it's running in the same = environment, chances are that it'll work out all right anyway, and so far it did. > > Fixing this kind of things can be nasty, I think -- for a simple > > text file, there's (AFAIK) no way to know the encoding but = guessing. > > Yes. The question is, how best to guess? And how best to override > the guesswork? > > > One way to handle it would probably be to have such an educated > > guess based on the system docutils is running on (assuming the file > > was typed in a dumb editor on the same machine), and to allow the > > encoding to be stated explicitly with a directive along the lines:: > >=20 > > .. encoding: cp1250 > > That's an alternative (already in the "To Do" list). It's not my > favorite, since it's ugly and can lie. When saving from a text = editor > a file could be re-encoded without the author noticing, and the > "encoding" directive would become wrong. Good point! ...and what do you get if you save from a browser = window (say, webmail written in reST) ? After the above experiment, I = think (but I'm definitely no authority here!!) that using the locale should = be the default way to go. --=20 Ueli From aahz@pythoncraft.com Tue Jun 18 14:04:55 2002 From: aahz@pythoncraft.com (Aahz) Date: Tue, 18 Jun 2002 09:04:55 -0400 Subject: [Doc-SIG] Non-ASCII Characters in reST (was: [Doc-SIG] docuti ls f eedback ) In-Reply-To: <2DB8BE7586F3D411B94F0008C786D940CF1AE7@eseczg22.e041zg02.esec.com> References: <2DB8BE7586F3D411B94F0008C786D940CF1AE7@eseczg22.e041zg02.esec.com> Message-ID: <20020618130455.GA10965@panix.com> On Tue, Jun 18, 2002, Schlaepfer, Ueli (ESEC ZG) wrote: > David Goodger wrote: >> >> This is an input encoding issue, the solution to which (you guessed >> it!) hasn't been implemented yet. I'm not even sure what the solution >> should be. Although I've worked with different "character sets" in >> the past (such as Japanese SJIS, and Chinese and Korean encodings), >> the encoding was always known beforehand. With Docutils, it won't be. >> Anyone with Unicode encoding/decoding experience, I'd appreciate some >> advice. > > Emacs does some guesswork concerning file encoding -- should we have a > look at that for a starter? Again, see PEP 263. As David said, there are a lot of problems with it, but it *does* start with Emacs as its base. > The language is much less of an issue, I think. Stating it in the > document if it's not what the default would be is easy enough to > understand, and such a statement won't turn into a lie as easily as the > encoding. A command-line option is a must, though; I don't expect an > American to state that his documents are in English, but I won't state > it if mine are in German either. So I need a way to tell the frontend > what language it should use. You edit the document to add the language. Otherwise, what if you're processing multiple documents in a single run, all in different languages? BTW, right-justified text looks ugly in a monospaced font. -- Aahz (aahz@pythoncraft.com) <*> http://www.pythoncraft.com/ Project Vote Smart: http://www.vote-smart.org/ From delza@mac.com Wed Jun 19 22:03:29 2002 From: delza@mac.com (Dethe Elza) Date: 19 Jun 2002 14:03:29 -0700 Subject: [Doc-SIG] Trouble using CVS version Message-ID: <1024520612.762.252.camel@laptop> I'm having trouble getting the CVS version of docutils to convert anything to HTML (or even parse a simple reST file). When I run tools/html.py or tools/publish.py on tools/test.txt I get errors for |problematic|, which I expect, and for the figure:: directive, which looks like a bug. When I fix these problems (by removal), I get only an empty document. The only thing which seems to come from the test.txt is the first comment. I've created a dead simple test: When it's nothing but text it works OK, but as soon as I add an underlined section, all the content disappears, including the text. Is this a known problem with the current CVS code? --Dethe From goodger@users.sourceforge.net Thu Jun 20 00:07:25 2002 From: goodger@users.sourceforge.net (David Goodger) Date: Wed, 19 Jun 2002 19:07:25 -0400 Subject: [Doc-SIG] Trouble using CVS version In-Reply-To: <1024520612.762.252.camel@laptop> Message-ID: Dethe Elza wrote: > I'm having trouble getting the CVS version of docutils to convert > anything to HTML (or even parse a simple reST file). ... > Is this a known problem with the current CVS code? No, there's no problem I'm aware of. The last checkins were late last night, and http://docutils.sf.net/spec/notes.html was automatically generated at 03:52 UTC (2002-06-19). I just tried running it with fresh code, no problems. Perhaps some old files have been left behind? -- David Goodger Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ From delza@mac.com Fri Jun 21 04:14:24 2002 From: delza@mac.com (Dethe Elza) Date: Thu, 20 Jun 2002 20:14:24 -0700 Subject: [Doc-SIG] Trouble using CVS version In-Reply-To: Message-ID: OK, I deleted everything and refreshed from CVS, re-installed. It's working OK now except for one rather weird problem: If I have a section marker named "Conflict Resolution" thus: Conflict Resolution =============== then I get an error, but any other wording work, ie: Conflict Revolution =============== is OK. It doesn't seem to be case sensitive, and it doesn't happen if it's just a paragraph, only a heading. I thought maybe there was a regex which was matching this, but I'll be damned if I can find it. Very curious. Glad to have the rest working--thanks for the help. Undoubtedly user error. --Dethe -- "Melting down holy grails to make silver bullets for my .357 Panacea" Dethe Elza (delza@burningtiger.com) Chief Mad Scientist Enfolding Systems (http://enfoldingsystems.com) Weblog: http://livingcode.ca/ From goodger@users.sourceforge.net Fri Jun 21 04:27:38 2002 From: goodger@users.sourceforge.net (David Goodger) Date: Thu, 20 Jun 2002 23:27:38 -0400 Subject: [Doc-SIG] Trouble using CVS version In-Reply-To: Message-ID: Dethe Elza wrote: > If I have a section marker named "Conflict Resolution" thus: > > Conflict Resolution > =============== > > then I get an error, but any other wording work, ie: > > Conflict Revolution > =============== > > is OK. What's the error? Please don't make me guess. Maybe it's because you don't have enough "=" below the title? The underline should be at least as long as the title. Maybe there's another title with the same text? -- David Goodger Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ From delza@mac.com Fri Jun 21 16:21:45 2002 From: delza@mac.com (Dethe Elza) Date: Fri, 21 Jun 2002 08:21:45 -0700 Subject: [Doc-SIG] Trouble using CVS version In-Reply-To: Message-ID: <98B9DA74-852A-11D6-A8E5-003065CA8E18@mac.com> Sorry, I should have posted the error, but it was on my linux box and I was writing from my Mac. There were definitely enough "=" because changing one letter made the problem go away. I didn't realize it was illegal to have two titles with the same text. That's probably it. (Checking) Yes, I had two titles with that text, and an internal link to it. Simple enough when I know where to look. Taking the internal link out also fixed the problem, so it's OK to have two identical titles, but not to link to them. The error I got was a looong traceback which ends: states.py, line 336, in underline nodes.py, line 667, in note_implicit_target nodes.py line 719, in clear_target_names if node.has_key('name'): AttributeError: 'NoneType' object has no attribute 'has_key' Which didn't say to me: duplicate reference. Thanks again, --Dethe -- "Melting down holy grails to make silver bullets for my .357 Panacea" Dethe Elza (delza@burningtiger.com) Chief Mad Scientist Enfolding Systems (http://enfoldingsystems.com) Weblog: http://livingcode.ca/ From goodger@users.sourceforge.net Fri Jun 21 22:37:14 2002 From: goodger@users.sourceforge.net (David Goodger) Date: Fri, 21 Jun 2002 17:37:14 -0400 Subject: [Doc-SIG] Trouble using CVS version In-Reply-To: <98B9DA74-852A-11D6-A8E5-003065CA8E18@mac.com> Message-ID: Dethe Elza wrote: > I didn't realize it was illegal to have two titles with the same > text. It's not illegal, but it becomes impossible to link to either by name because of the common name. If you run a front end with the "-v" or "--verbose" option, you should see a level-1 (info) system message:: Reporter: INFO (1) Duplicate implicit target name: "Conflict Resolution". However, > The error I got was a looong traceback which ends: > > states.py, line 336, in underline > nodes.py, line 667, in note_implicit_target > nodes.py line 719, in clear_target_names > if node.has_key('name'): > AttributeError: 'NoneType' object has no attribute 'has_key' > > Which didn't say to me: duplicate reference. That's definitely a bug. No input data should ever cause Docutils to crash. I wasn't able to duplicate the problem from your description, although it *did* reveal a related bug (and very tricky to fix too). You aren't running Docutils from the 0.1 release, are you? If you are, please reinstall Docutils from the latest snapshot, always available at http://docutils.sf.net/docutils-snapshot.tgz. Could you please send me an input file and the command that generates this traceback? Please also tell me your Python version and Docutils version (snapshot date). -- David Goodger Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ From goodger@users.sourceforge.net Fri Jun 21 22:57:40 2002 From: goodger@users.sourceforge.net (David Goodger) Date: Fri, 21 Jun 2002 17:57:40 -0400 Subject: [Doc-SIG] Trouble using CVS version In-Reply-To: Message-ID: Dethe Elza wrote: > I'm working with the CVS version, loaded fresh yesterday. Python 2.2.1. I realized this immediately after hitting the Send button, from the title. Sorry! -- David Goodger Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ From delza@mac.com Fri Jun 21 22:49:43 2002 From: delza@mac.com (Dethe Elza) Date: Fri, 21 Jun 2002 14:49:43 -0700 Subject: [Doc-SIG] Trouble using CVS version In-Reply-To: Message-ID: Ah, the --verbose option is good to know about. That does report the problem (and a couple others I hadn't figured out yet) before crashing. I'm working with the CVS version, loaded fresh yesterday. Python 2.2.1. I'll send the file and command as soon as I can get it from my laptop. Last night I ran an update command under (Debian) Linux which has completely hosed all network connectivity. I have an external floppy drive around somewhere, but digging it out right now would just distract from getting networking fixed. --Dethe -- "Melting down holy grails to make silver bullets for my .357 Panacea" Dethe Elza (delza@burningtiger.com) Chief Mad Scientist Enfolding Systems (http://enfoldingsystems.com) Weblog: http://livingcode.ca/ From grant-h@msn.com Mon Jun 24 04:34:42 2002 From: grant-h@msn.com (Grant Harris) Date: Sun, 23 Jun 2002 20:34:42 -0700 Subject: [Doc-SIG] Older Python Documentation Message-ID: <000001c21b30$149fc3b0$32cae40c@homer> Hello, I'm working on a web site (http://www.webdocs.org) that hosts the current and older releases of the official Python documentation, along with some other Python-related docs. I currently have Python documentation from as far back as version 1.4 on the site, but nothing older. If possible, I'd like to include as many releases of the Python documentation as I can find (if not all of them). However, I can't seem to find anything prior to Python 1.4. (I did happen to find some tex files for a couple older versions, but no html files.) Also, I'm relatively new to Python (less than a year), so I don't even know which older versions were officially released. For instance, I know that there was a version 1.3 and a 1.2 released, but was there ever a version 1.2.1 or 1.3.1? My guess is that no one today would even care about documentation from that far back. But personally I think it's cool to be able to see how Python has evolved over the years. If anyone knows where I can get documentation for versions of Python older than 1.4, please let me know. Regards, -Grant From tim.one@comcast.net Mon Jun 24 18:51:25 2002 From: tim.one@comcast.net (Tim Peters) Date: Mon, 24 Jun 2002 13:51:25 -0400 Subject: [Doc-SIG] Older Python Documentation In-Reply-To: <000001c21b30$149fc3b0$32cae40c@homer> Message-ID: [Grant Harris] > I'm working on a web site (http://www.webdocs.org) that hosts the > current and older releases of the official Python documentation, along > with some other Python-related docs. Cool! > I currently have Python documentation from as far back as version 1.4 on > the site, but nothing older. I just did a Google search on "Python 1.3" and one of the top hits was www.umich.edu/~archive/atari/Mint/Python/ from which you can get Python-1.3-docs.tar.gz It matches my memory: it's a bunch of .tex files, along with a makefile and assorted scripts to generate other formats. http://ftp.fcaglp.unlp.edu.ar/pub/python/src/ appears to have a tarball for Python 1.2 too. > If possible, I'd like to include as many releases of the Python > documentation as I can find (if not all of them). However, I can't seem > to find anything prior to Python 1.4. (I did happen to find some tex > files for a couple older versions, but no html files.) HTML was new-fangled stuff back then; Guido didn't have time to generate all possible formats, unlike Fred today, who does nothing else . > Also, I'm relatively new to Python (less than a year), so I don't even > know which older versions were officially released. For instance, I > know that there was a version 1.3 and a 1.2 released, but was there ever > a version 1.2.1 or 1.3.1? No. You can extract a list of all historic releases from the file Misc/HISTORY in the current Python source distribution. > My guess is that no one today would even care about documentation from > that far back. But personally I think it's cool to be able to see how > Python has evolved over the years. If you go back far enough, Guido used to maintain the docs in FrameMaker. Good luck . From goodger@users.sourceforge.net Thu Jun 27 02:37:56 2002 From: goodger@users.sourceforge.net (David Goodger) Date: Wed, 26 Jun 2002 21:37:56 -0400 Subject: [Doc-SIG] Trouble using CVS version In-Reply-To: Message-ID: I've just checked in a reworking of how ``docutils.nodes.document`` does its name/id bookkeeping. This removes a subtle bug; details at http://docutils.sourceforge.net/spec/notes.html#bugs (but not for long). Dethe, I think it might solve the problem you reported. Could you try it out please? If the problem persists, please send details. Thanks. -- David Goodger Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ From goodger@users.sourceforge.net Thu Jun 27 02:58:30 2002 From: goodger@users.sourceforge.net (David Goodger) Date: Wed, 26 Jun 2002 21:58:30 -0400 Subject: [Doc-SIG] Simplified table syntax proposals (reStructuredText) Message-ID: I've added some new, simplified but limited, alternative table syntax proposals (http://docutils.sf.net/spec/rst/problems.html#tables, alternatives 3, 4, and 5), incorporating an idea from Simon Hefti. There's a better example of alternative 3 in the notes.txt file (http://docutils.sf.net/spec/notes.html#bugs). Could people please take a look at these alternatives and tell me what they think? Thank you. -- David Goodger Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ From Paul.Moore@atosorigin.com Thu Jun 27 12:35:45 2002 From: Paul.Moore@atosorigin.com (Moore, Paul) Date: Thu, 27 Jun 2002 12:35:45 +0100 Subject: [Doc-SIG] Simplified table syntax proposals (reStructuredText ) Message-ID: <714DFA46B9BBD0119CD000805FC1F53B01B5B3D2@UKRUX002.rundc.uk.origin-it.com> From: David Goodger [mailto:goodger@users.sourceforge.net] > I've added some new, simplified but limited, alternative table syntax > proposals (http://docutils.sf.net/spec/rst/problems.html#tables, > alternatives 3, 4, and 5), incorporating an idea from Simon Hefti. > There's a better example of alternative 3 in the notes.txt file > (http://docutils.sf.net/spec/notes.html#bugs). > > Could people please take a look at these alternatives and tell me what > they think? Thank you. [[Disclaimer: I don't use tables much in raw text, so I don't have much of an opinion from a writer's point of view. This is basically a view in the context of being able to read the markup in raw form, which I feel is important...]] I find option (3) almost totally unreadable. Option (5) is OK, but the inability to have blank cells in column 1 makes tables like this:: +-----+-----+ | | A | +-----+-----+ | 1 | A1 | +-----+-----+ unrepresentable. And I suspect that such tables are fairly common (spreadsheet type layouts). Option (4) is the best of the 3, from that point of view. But I don't like the (mis?) use of the bullet list notation. I'd stick with the current approach. It's verbose, but very clear. The need to pad out columns to type the | characters is a (mild) nuisance. But for that, option (2) is fine. I feel that minimalism beyond that point is useless - it hampers readability and expressiveness, for no clear gain in ease of use. [If reST ever grows a way of declaring options for a document, maybe having a "table-format=boxed/minimal" option to choose between table formats (1) and (2) would be worthwhile, but I imagine tghat the price is not worth the gain. No, stick with things as they are.] Paul. From goodger@users.sourceforge.net Fri Jun 28 05:36:20 2002 From: goodger@users.sourceforge.net (David Goodger) Date: Fri, 28 Jun 2002 00:36:20 -0400 Subject: [Doc-SIG] Docutils updates -- encodings and I/O Message-ID: I've just added support for Unicode and file encodings. The new ``docutils.io`` module implements a uniform API for a variety of input & output mechanisms. Please check it out, especially those of you who write in more than plain ASCII. Download the latest snapshot from: http://docutils.sf.net/docutils-snapshot.tgz -- David Goodger Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ From goodger@users.sourceforge.net Fri Jun 28 05:41:40 2002 From: goodger@users.sourceforge.net (David Goodger) Date: Fri, 28 Jun 2002 00:41:40 -0400 Subject: [Doc-SIG] Simplified table syntax proposals (reStructuredText ) In-Reply-To: <714DFA46B9BBD0119CD000805FC1F53B01B5B3D2@UKRUX002.rundc.uk.origin-it.com> Message-ID: Moore, Paul wrote: > I find option (3) almost totally unreadable. Did you look at this example? It's much clearer: http://docutils.sf.net/spec/notes.html#bugs The example in the problems.txt file shows all possible variations in a single small table, so it's bound to be difficult. Thanks for your comments! -- David Goodger Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ From Paul.Moore@atosorigin.com Fri Jun 28 11:20:08 2002 From: Paul.Moore@atosorigin.com (Moore, Paul) Date: Fri, 28 Jun 2002 11:20:08 +0100 Subject: [Doc-SIG] Simplified table syntax proposals (reStructuredText ) Message-ID: <714DFA46B9BBD0119CD000805FC1F53B01B5B3D6@UKRUX002.rundc.uk.origin-it.com> From: David Goodger [mailto:goodger@users.sourceforge.net] > Moore, Paul wrote: > > I find option (3) almost totally unreadable. > > Did you look at this example? It's much clearer: > > http://docutils.sf.net/spec/notes.html#bugs > > The example in the problems.txt file shows all possible > variations in a single small table, so it's bound to be > difficult. Yes, that looks a *lot* better. I think the limitation of not being able to have multi-line cells could be significant, but otherwise it looks reasonable. Depends on what the design constraints are (functionally complete, vs easy to enter, vs easy to read in raw form, ...) I don't have enough use cases to judge on that. I get the impression that functional completeness has been a criterion in previous cases, though. Paul. From Simon.Budig@unix-ag.org Fri Jun 28 19:34:15 2002 From: Simon.Budig@unix-ag.org (Simon Budig) Date: Fri, 28 Jun 2002 20:34:15 +0200 Subject: [Doc-SIG] References in the same line as the target text Message-ID: <20020628203415.A30862@vmax.unix-ag.uni-siegen.de> Hi everybody. I am currently poking around in the reStructuredText stuff of the docutils. I like it. However, there is one thing that really bugs me a bit. It seems impossible to get a Reference (Link) without having to type the name twice, which is a point where errors occur easily. Also sometimes it is not feasible to have the link targets stand out after a paragraph (where they interrupt the read flow) or at the end of the text (hard to keep in sync in case of changes to the target text). I would like to have some kind of inline link markup. I think a very logical way would be something like the following reference to Python_(http://www.python.org) or this Reference to `The GIMP`_(http://www.gimp.org). IMHO this is a logical and unintrusive extension to the Link Syntax (If a ')' is in the Link itself it should be escaped, but maybe somebody has a better idea for the delimiters). I am currently not sure if it is feasible to have these Links added to the target name list, because this might result in inconsistencies like here_(http://foo.bar) and here_(http://bar.baz). Or leave this problem to the user and allow also anonymous inline links like here__(http://blubb.bla). I think this addition would make it way easier to write structured text with links. But it is perfectly possible that I missed something obvious, since I am pretty new to this field. Please tell me what you think... :-) Bye, Simon -- Simon.Budig@unix-ag.org http://www.home.unix-ag.org/simon/ From goodger@users.sourceforge.net Sat Jun 29 01:30:04 2002 From: goodger@users.sourceforge.net (David Goodger) Date: Fri, 28 Jun 2002 20:30:04 -0400 Subject: [Doc-SIG] References in the same line as the target text In-Reply-To: <20020628203415.A30862@vmax.unix-ag.uni-siegen.de> Message-ID: Simon Budig wrote: > It seems impossible to get a Reference (Link) without having to type > the name twice, which is a point where errors occur easily. You can avoid typing the name twice if you use anonymous links:: This is an `example reference`__. __ http://www.example.org But I take it you know this. :-) > Also sometimes it is not feasible to have the link targets stand out > after a paragraph (where they interrupt the read flow) or at the end > of the text (hard to keep in sync in case of changes to the target text). > > I would like to have some kind of inline link markup. I think a very > logical way would be something like the following reference to > Python_(http://www.python.org) or this Reference > to `The GIMP`_(http://www.gimp.org). I can see why you might think link targets after a paragraph break the flow. I often group targets at the end of sections, where a break in the flow is not so noticeable. I agree that keeping references and targets in sync can be difficult when using anonymous links. However, I can't reconcile your notion that targets *after* a paragraph break the flow, but targets *within* a paragraph don't. To me, having the URL inside the text breaks the flow much more severely, *especially* when combined with syntax. If it's just an issue of keeping references and targets in sync, and you were only interested in the processed output, I could understand. But then, you wouldn't have any objection to putting targets after paragraphs. One of the major reasons for the current link syntax is a reaction against the inline syntax in StructuredText (one of reStructuredText's prececessors and sources), similar to what you propose. See http://docutils.sf.net/spec/rst/problems.html#hyperlinks for details. If you do want the references in the text, why not just put them in directly? For example: Here's a reference to Python (http://www.python.org) and one to The GIMP (http://www.gimp.org). One of the goals of reStructuredText is to be equally readable both before and after processing. It's for documents that are meant to be read in source (plaintext) form as well as processed form. If you're willing to have URLs in the middle of sentences in your source files, why not in the HTML? It's a reasonable compromise. > IMHO this is a logical and unintrusive extension to the Link Syntax IMHO, it's a step backward. (Gotta be brutally honest; life's too short ;-) But thanks for the feedback! With any new syntax, be it a text markup or a programming language, it takes time to get used to unfamiliar corners. Perhaps you just need to give it a chance? -- David Goodger Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ From Simon.Budig@unix-ag.uni-siegen.de Sat Jun 29 14:48:18 2002 From: Simon.Budig@unix-ag.uni-siegen.de (Simon Budig) Date: Sat, 29 Jun 2002 15:48:18 +0200 Subject: [Doc-SIG] References in the same line as the target text In-Reply-To: ; from goodger@users.sourceforge.net on Fri, Jun 28, 2002 at 08:30:04PM -0400 References: <20020628203415.A30862@vmax.unix-ag.uni-siegen.de> Message-ID: <20020629154817.A42426@vmax.unix-ag.uni-siegen.de> Hi all, hi David. First some words why I want to use reStructuredText and what motivates me to bring this up. I made the experience with my personal homepage, that there are two major problems for the maintainance of the (small) site. 1) keeping the structure consistent and have the menu refer to all available pages. Especially creating new graphical buttons for a menu is a pain I tend to avoid. 2) Making content creation easy. Even though i have lots of experience with HTML I still hate writing it, because it is so easy to break stuff. The latter is my reason why I am interested in reStructuredText. I basically want to have a system where I could drop in a .rst and some Apache magic will serve this as HTML with my customized design. David Goodger (goodger@users.sourceforge.net) wrote: > Simon Budig wrote: [...] > > I would like to have some kind of inline link markup. I think a very > > logical way would be something like the following reference to > > Python_(http://www.python.org) or this Reference > > to `The GIMP`_(http://www.gimp.org). > > I can see why you might think link targets after a paragraph break the flow. > I often group targets at the end of sections, where a break in the flow is > not so noticeable. I agree that keeping references and targets in sync can > be difficult when using anonymous links. It is also difficult if you use named links. It is even more if you group the targets at the end of a larger section and have a big distance between the two points of interest. The main reason for this is, that the text identifying the link appears twice. This is one of the few points where you can easily introduce serious errors in reST-text and make maintaining the text harder: If you want to change the text you have to do this at two places. Since my main motivation is to make the maintainance of stuff easier this bugs me. > However, I can't reconcile your notion that targets *after* a paragraph > break the flow, but targets *within* a paragraph don't. To me, having the > URL inside the text breaks the flow much more severely, *especially* when > combined with syntax. Oh - maybe it is just me, but skipping an URL in braces is easy for me. However, when there are a bunch of links at the end of a section I have to search for the start of the next "real" text... On the other hand it might even be useful to have the links directly ready for cut'n'paste/bookmarking while reading a text (see below). Note that you have to know something about reST to 1) understand that an '_' indicates a link (not trivial for a newbie!) and 2) find the proper link for the target you are currently interested in (also not trivial). [...] > One of the major reasons for the current link syntax is a reaction against > the inline syntax in StructuredText (one of reStructuredText's prececessors > and sources), similar to what you propose. See > http://docutils.sf.net/spec/rst/problems.html#hyperlinks for details. Btw - I remember having seen the design goals mentioned there, but I am unable to find them again. Maybe you should add a link there. You mention that the forms mentioned at that link are neither intuitive nor unobtrusive and I agree to that. However when I test my proposed syntax against this (ok, this has to be subjective...) I think, that at least the intuitivity is given. I have seen lots of texts where an URL is mentioned in braces inline with the text and it seems natural to me. The addition of an underscore is barely noticeable then. The "unobstrusitivity" is a bit harder to judge (it starts with interpreting the word, because I am not a native speaker... :-) A problem surely is that there is text in the reST source that does not get rendered to the final output - maybe a bit surprising. However, using Python_(http://www.python.org) versus using Python_ or Python (http://www.python.org) would be the choice of the author. .. _Python: http://www.python.org I also think of my proposal as unobstrusive, because if you read the reST it does not say "HELLO! THIS IS SYNTAX!" (versus e.g. Python_{http://www.python.org} - Ugh!). As mentioned above I have seen URLs in braces quite often and I assume that the average reader is used to it or able to interpret it correctly, because the meaning of braces (for remarks like this) are familiar to everybody and the URL in this context is exactly this: A remark to the topic just mentioned. > If you do want the references in the text, why not just put them in > directly? For example: > > Here's a reference to Python (http://www.python.org) and one to > The GIMP (http://www.gimp.org). > > One of the goals of reStructuredText is to be equally readable both before > and after processing. It's for documents that are meant to be read in > source (plaintext) form as well as processed form. If you're willing to > have URLs in the middle of sentences in your source files, why not in the > HTML? It's a reasonable compromise. This does not work for relative links. Also for my personal homepage as mentioned at the beginning of the Mail I am pretty picky, since graphical stuff has a pretty high priority in my life... So while this is acceptable in plaintext (this is one of my preferred ways to mention URLs in plaintext) it is not in HTML, since HTML has a better (HTML-specific) way to handle links. BTW: You mention the goal "equally readable" for reST. I personally would replace this with "equally useable for the reader". IMO this is not the same (the latter is a broader goal) and Links are a good way to demonstrate this. Links are meant to point to an external reference. So if a user reaches a Link he usually wants to a) follow this link immediately, b) create a bookmark or c) ignore it. In HTML all three tasks are easily done, provided there is a slight hint in the text formatting, that there actually is a link. In reST the goals a) and b) are seriously hampered, because the URL necessary to do the action maybe everywhere in the text and the user has no choice but to search the whole text for the matching identifier (which might be in a totally "wrong" place in case of multiple links to the same target) and then perform his action. So the links in reST are less "useable"... My proposal would bring the URL close to the point where it is relevant and make a) and b) way easier. Of course it is a bit harder to ignore the URL, but since braces are very common to indicate that something has less importance I think that this is not too hard to ignore the link. > > IMHO this is a logical and unintrusive extension to the Link Syntax > > IMHO, it's a step backward. (Gotta be brutally honest; life's too short ;-) Backward? I do not want to remove functionality from reST... :-) Sorry, I fail to see the badness of my proposal. I neither see any real bad impacts on the readability of the reST nor something that would wreak havoc with the Syntax of reST (or do I miss something here?). > But thanks for the feedback! > > With any new syntax, be it a text markup or a programming language, it takes > time to get used to unfamiliar corners. Perhaps you just need to give it a > chance? I definitely will give it a shot. Writing reST is so easy compared to HTML that I am definitely attracted towards doing my Homepage with this stuff. However, there is this point that bugs me and I have a real chance to (IMO) improve this point - it would be dumb to not to try it... :-) Phew, this is one of my longer mails, thanks for reading it to the end... Bye, Simon -- Simon.Budig@unix-ag.org http://www.home.unix-ag.org/simon/