From wyatt at syndesis.com Tue Apr 6 11:55:46 2004 From: wyatt at syndesis.com (Derek Wyatt) Date: Tue Apr 6 11:55:04 2004 Subject: [Doc-SIG] Creating a new type of document Message-ID: <20040406115546.B10327@syndesis.com> Hi folks, First off... thanks for the tool. I love the markup language. I'm trying to use this to create a documentation centre within the company that i work for. I like the idea of PEPs (as i've stated on a previous message) but I don't like the PEP acronym (for sake of argument, this will be DED in this email). It simply doesn't make sense here. What i want is to have my own type of reST type of document that has a DED feel (with the top navigation bar sans the gif). I need to add, automatically, to a standard reST document, the following: o automatic recognition of "DED nn" as something that needs to be a relative link to "ded-00nn.html" a la PEP. o automitic inclusion of the top set of links (a la PEP), taking you to the top level directory, showing you DED 0, and also showing the DED source. What i don't need, that the PEPs have is: o all of the python "stuff" -- CVS links, python home links, python pep index links, etc etc.. What am i writing to accomplish this? I am getting a bit of a feel for how the system works and it looks like i'm not going to be writing a reader or parser since the file will be basic reST. However i think i need to write a transform, writer and a front-end. Is this correct? I could write an html munger that takes the output of the html.py front end and puts in the "DED nn" links and the links at the top, but it seems much cleaner to write something that can intercept the reST parsed output into XML and insert the stuff there. Thanks again! Derek -- ----------------------------------------------------------- Derek Quinn Wyatt | Phone: (905) 886-7818 ext. 2314 Syndesis Engineering | Fax: (905) 886-9076 Toronto, Ontario, CAN | Email: wyatt@syndesis.com ----------------------------------------------------------- "Go away or I will replace you with a small, more cost-effective shell script." "Necessary" Legalese: This email communication is CONFIDENTIAL. If you are not the intended recipient, you may not use, copy or disclose to anyone the message or any information contained in the message and I ask that you please notify me at the telephone number shown above or by return email and delete this communication immediately. Thank you. From goodger at python.org Fri Apr 9 19:23:03 2004 From: goodger at python.org (David Goodger) Date: Fri Apr 9 19:23:09 2004 Subject: [Doc-SIG] Creating a new type of document In-Reply-To: <20040406115546.B10327@syndesis.com> References: <20040406115546.B10327@syndesis.com> Message-ID: <40773057.1080308@python.org> Derek Wyatt wrote: > First off... thanks for the tool. I love the markup language. :-) > I'm trying to use this to create a documentation centre within the > company that i work for. I like the idea of PEPs (as i've stated on > a previous message) but I don't like the PEP acronym Understandable, if it doesn't fit your documents. > What am i writing to accomplish this? I am getting a bit of a feel > for how the system works and it looks like i'm not going to be > writing a reader or parser since the file will be basic reST. > However i think i need to write a transform, writer and a front-end. > Is this correct? I think you'll need: * a Reader (subclasses of docutils.readers.pep classes should suffice), * transforms (subclasses/variations of docutils.transforms.peps classes), * a Writer (subclasses of docutils.writers.pep_html classes), * a template file (variation of tools/pep-html-template), * possibly a stylesheet (variation of tools/stylesheets/pep.css), and * a front end (variation of tools/pep.py; don't use pep2html.py, which contains a lot of non-Docutils legacy code). It may be cleaner to generalize some of the PEP-specific classes for easier subclassing; if so, we could add new generic "proposal" modules that PEP modules could use. > I could write an html munger that takes the output of the html.py > front end and puts in the "DED nn" links and the links at the top, > but it seems much cleaner to write something that can intercept the > reST parsed output into XML and insert the stuff there. Agreed. You may want to take a look at other projects that have done the same thing: * PEGs (Proposals for Enhancing Gzz): http://himalia.it.jyu.fi/gzzdoc/pegboard/pegboard.gen.html * GLEPs (Gentoo Linux Enhancement Proposals): http://www.gentoo.org/proj/en/glep/ Both of these have adopted Python's PEP system and reStructuredText for their own proposals. If anyone knows of other projects that have done the same thing, please let me know. I haven't looked at any of the actual code they use, so I can't say if it's done "correctly". -- David Goodger http://python.net/~goodger For hire: http://python.net/~goodger/cv From amk at amk.ca Fri Apr 9 22:04:01 2004 From: amk at amk.ca (A.M. Kuchling) Date: Fri Apr 9 22:04:45 2004 Subject: [Doc-SIG] Creating a new type of document In-Reply-To: <40773057.1080308@python.org> References: <20040406115546.B10327@syndesis.com> <40773057.1080308@python.org> Message-ID: <20040410020401.GA576@rogue.amk.ca> On Fri, Apr 09, 2004 at 07:23:03PM -0400, David Goodger wrote: > Both of these have adopted Python's PEP system and reStructuredText > for their own proposals. If anyone knows of other projects that have Interesting; perhaps writing a HOWTO on doing this would encourage more projects to adopt the docutils toolset. --amk From wyatt at syndesis.com Tue Apr 13 07:47:35 2004 From: wyatt at syndesis.com (Derek Wyatt) Date: Tue Apr 13 07:49:14 2004 Subject: [Doc-SIG] Creating a new type of document In-Reply-To: <40773057.1080308@python.org>; from goodger@python.org on Fri, Apr 09, 2004 at 07:23:03PM -0400 References: <20040406115546.B10327@syndesis.com> <40773057.1080308@python.org> Message-ID: <20040413074735.B6239@syndesis.com> : I think you'll need: : : * a Reader (subclasses of docutils.readers.pep classes should : suffice), : * transforms (subclasses/variations of docutils.transforms.peps : classes), : * a Writer (subclasses of docutils.writers.pep_html classes), : * a template file (variation of tools/pep-html-template), : * possibly a stylesheet (variation of tools/stylesheets/pep.css), and : * a front end (variation of tools/pep.py; don't use pep2html.py, which : contains a lot of non-Docutils legacy code). : : It may be cleaner to generalize some of the PEP-specific classes for : easier subclassing; if so, we could add new generic "proposal" modules : that PEP modules could use. This is something i would prefer. I'm really not sure when i'm going to have time to do it though -- one of the reasons i chose docutils is because i'm busy enough as it is :) -- so if someone else is hot to do this then don't wait for me. : Agreed. You may want to take a look at other projects that have done : the same thing: : : * PEGs (Proposals for Enhancing Gzz): : http://himalia.it.jyu.fi/gzzdoc/pegboard/pegboard.gen.html : : * GLEPs (Gentoo Linux Enhancement Proposals): : http://www.gentoo.org/proj/en/glep/ : : Both of these have adopted Python's PEP system and reStructuredText : for their own proposals. If anyone knows of other projects that have : done the same thing, please let me know. I haven't looked at any of : the actual code they use, so I can't say if it's done "correctly". I'll have to contact these groups and see if i can get their source. Based on PEP, GLEP, PEG and my own, I might just be able to come up with the general solution that suits everyone. For now though i've got a hack working. I munged up html4css1.py to shove in some HTML comments in the spots i needed. Then i post-processed the output and replaced those with something functional. Not the ideal solution to be sure, but it works for now. Give me some time and i hope to put in a better solution. Thanks again, Derek : : -- : David Goodger http://python.net/~goodger : For hire: http://python.net/~goodger/cv -- ----------------------------------------------------------- Derek Quinn Wyatt | Phone: (905) 886-7818 ext. 2314 Syndesis Engineering | Fax: (905) 886-9076 Toronto, Ontario, CAN | Email: wyatt@syndesis.com ----------------------------------------------------------- "Go away or I will replace you with a small, more cost-effective shell script." "Necessary" Legalese: This email communication is CONFIDENTIAL. If you are not the intended recipient, you may not use, copy or disclose to anyone the message or any information contained in the message and I ask that you please notify me at the telephone number shown above or by return email and delete this communication immediately. Thank you. From goodger at python.org Sat Apr 17 21:42:07 2004 From: goodger at python.org (David Goodger) Date: Sat Apr 17 21:42:19 2004 Subject: [Doc-SIG] "role" directive added to reStructuredText Message-ID: <4081DCEF.90203@python.org> Just added to the Docutils codebase: a "role" directive that creates a custom interpreted text role and registers it with the parser. This input: .. role:: custom some :custom:`text` parses to this (internal pseudo-XML): some text It produces the following HTML: some text The directive is a simple initial implementation that may be expanded in the future, as requirements become known/clear. Details here: http://docutils.sf.net/spec/rst/directives.html#role CVS snapshot: http://docutils.sf.net/docutils-snapshot.tgz -- David Goodger http://python.net/~goodger For hire: http://python.net/~goodger/cv