Re: reStructuredText

Hello, On Thu, 12 Jun 2003 21:00:45 -0400 Jon Parise <jon@php.net> wrote: > On Thu, Jun 12, 2003 at 08:20:17PM +0200, Pierre-Alain Joye wrote: > I use a text editor to edit reST. I don't think user documentation > for a PEAR package really requires advanced editing features such as > those provided by an office tool. I just need headings, example > blocks, and hyperlinks. Syntactially, reST is simpler than HTML, and > I'm sure most PEAR developers don't require an office tool to author > HTML. If I discuss as a pure developper, I really do not care. I'll take the time to learn the necessary things to write the doc. If I do not have the time, doh, they can read the API docs and follow the samples. We do not choose to provide only the last way. People are ready to help us to write good endusers documentations, here comes "office" tools. Office tools means only to provide them something like a template with stylesheets or whatever, or a tool with the same comfort as these office tools. They will not help us if they cannot work as they work with their own documents. > I don't want to wade into the "one tool to rule them all" argument any > further. It's becoming one of those "When you have a hammer, > everything starts to look like a nail" kinds of things. it's more a question of confusions, waste of energies rather than anything else. We have got a meeting, that has been discussed as well as a lot of others things. I'm still wondering where we go... > What do you have against Python? I get the feeling if the reST tools > I advocate were written in Perl or some language with which PHP folks > were more comfortable, this would be less of an issue. I have nothing against Python, I even like it in some ways (except the indent things which remember the old times of cobol :P). I have something against using an externel tools (tools!==format) in preference to a something that does not need a lot of work to be a very good tool and done with PHP. Christian told us something about his future bitflux editor which should be able to work with docbook, another good point. > Again, I advocate the Python tools because they already exist and work > well. The code speaks for itself, and I'm sorry that you have to 'rpm > -i python' (or whatever your preferred installation method is) in > order to use them. I advocate the "world #1 ;)" script langage can get its tools to work with documentation. We have one very good and modular tool, not that much work to make it near perfect. A good way (as you said) is to add a reST converter to it (volunteers?). I advocate too that any developer should be able to work locally with some default tools provided with PEAR (bundled) as well as the peardoc team. We should not forget we do not always write document, especially enduser documentations, ourselves. > This is getting silly. yes :P however do not take it personnaly :). This is a really important point to me (as the installer, and such core part of PEAR). That's why I fight hard to get something really good for everyone (taking care of the many discussions I got with some docs writers before the meeting). As my conclusion, We have had this discussions in the past, we have 2 visions. That has been discussed in the meeting. As far as we can use one tool to work with whatever format you would like, that will sound good to me. This tool should be bundled or be part of the PFC. Provide all necessary stuffs to work with PEAR document (inline and/or endusers). This is my goal (and I'm quit sure not only mine). And actually, phpdocu fits most of these requirements, and is able to support reST if you like to write doc with this format. By the way, there is a peardoc list, we should use this list to discuss documentation related things. Best regards, pierre