From: Felix W. <Fel...@gm...> - 2004-05-11 20:34:27
|
As it's (IMO) currently somehow messed up, I propose to do a cleanup of the doc (directory) structure: Move docs/* to docs/user/, move spec/ to docs/spec/ (or docs/specification/?), move licenses/ to docs/licenses/. Move FAQ.txt to docs/user/FAQ.txt. Move 'Acknowledgements' from HISTORY.txt to docs/CREDITS.txt. Create docs/notes/, split up spec/notes.txt to docs/notes/bugs.txt, docs/notes/todo.txt, docs/notes/ideas.txt, docs/develop/policies.txt, docs/develop/website.txt, docs/develop/release.txt. Move 'Future Plans' from HISTORY.txt to docs/notes/ideas.txt or docs/notes/todo.txt. Any thoughts? -- When replying to my email address, ensure that the mail header contains 'Felix Wiemann'. Please don't send unrequested mails > 64 KB. <http://www.ososo.de/> |
From: Lele G. <le...@na...> - 2004-05-11 22:19:56
|
>>>>> "Felix" =3D=3D Felix Wiemann <Fel...@gm...> writes: Felix> Any thoughts? Agreed! We talked about something similar several months ago, but didn't reach a final decision. At that time, I contribuited the italian_ versions_ of several key documents. I'm almost neutral on where they live [with a little bias for svn over CVS :] but, should they go in? Where? thanx&bye, lele. .. _italian: http://docit.bice.dyndns.org/static/ReST/ .. _versions: http://docit.bice.dyndns.org/cgi-bin/viewcvs.cgi/ReST/ --=20 nickname: Lele Gaifax | Quando vivr=C3=B2 di quello che ho pensato ieri real: Emanuele Gaifas | comincer=C3=B2 ad aver paura di chi mi copia. email: le...@se... | -- Fortunato Depero, 1929. |
From: Felix W. <Fel...@gm...> - 2004-05-13 18:15:40
|
Lele Gaifax wrote: > [...] I contribuited the italian_ versions_ of several key > documents. I'm almost neutral on where they live [with a little bias > for svn over CVS :] but, should they go in? Where? If they go into the main docutils tree, they (IMO) always have to be kept up to date, which seems pretty hard, if not impossible. Thus I suggest either * creating a CVS module for translated docs or * keeping the files in a sandbox or * leaving them at docit.byce.dyndns.org and simply adding a link to your translations on the main Docutils web page. In the former two cases they can be automatically made available on the Docutils website. -- When replying to my email address, ensure that the mail header contains 'Felix Wiemann'. Please don't send unrequested mails > 64 KB. <http://www.ososo.de/> |
From: David G. <go...@py...> - 2004-05-11 23:51:03
|
Felix Wiemann wrote: > Any thoughts? I'm in general agreement, but I'd like to think about the specifics. Please don't implement your plan quite yet. I'd like to give others a chance to voice their opinions first. -- David Goodger |
From: David G. <go...@py...> - 2004-05-12 20:55:58
|
[Felix Wiemann] > As it's (IMO) currently somehow messed up, I propose to do a cleanup > of the doc (directory) structure: As I said before, I'm in general agreement. Here are my thoughts about the specifics. > Move docs/* to docs/user/, move spec/ to docs/spec/ (or > docs/specification/?), docs/spec/ (It's frequently used, so keep it short.) > move licenses/ to docs/licenses/. No, leave licenses/ in the root. They're too important to bury. > Move FAQ.txt to docs/user/FAQ.txt. I think this should stay in the root, along with HISTORY, COPYING, and README. All docs in the root must have UPPERCASE filenames (+".txt"). > Move 'Acknowledgements' from HISTORY.txt to docs/CREDITS.txt. ACK.txt, in the root. (Better name? How about THANKS.txt?) We're not listing who did what, so "credits" isn't appropriate. > Create docs/notes/, docs/dev/ Move spec/howto/ to docs/dev/howto/. > split up spec/notes.txt to docs/notes/bugs.txt, BUGS.txt, at the root level. For descriptions of known bugs. Add a "How To Report A Bug" section, like Subversion's (http://svn.collab.net/viewcvs/svn/trunk/BUGS?rev=9086&view=markup). > docs/notes/todo.txt, docs/dev/todo.txt > docs/notes/ideas.txt, Where is the text coming from? > docs/develop/policies.txt, > docs/develop/website.txt, docs/develop/release.txt. docs/dev/policies.txt, docs/dev/website.txt, docs/dev/release.txt > Move 'Future Plans' from HISTORY.txt to docs/notes/ideas.txt or > docs/notes/todo.txt. Perhaps make "Future Plans" into a "Priorities" section of docs/dev/todo.txt. > Any thoughts? Add docs/index.txt, a table of contents that lists and describes all the subdirectories and documents. As Lele pointed out, we haven't decided where to put translated docs. Should they go in the same directory tree as the originals, or be a separate CVS module? It would be useful to keep the CVS history of moved files. To do so, we need to supply SourceForge with a script for modifying the Docutils CVS repository (http://sf.net/docman/display_doc.php?docid=768&group_id=1#repositoryrestructure). There are some other repository cleanups I want to do, so we should coordinate. -- David Goodger |
From: Felix W. <Fel...@gm...> - 2004-05-13 19:03:19
|
David Goodger wrote: > Felix Wiemann wrote: > >> move licenses/ to docs/licenses/. > > No, leave licenses/ in the root. They're too important to bury. Really? Who reads licenses?! Don't you think adding a reference to the docs/licenses/ directory and adjusting the existing links in COPYING.txt is sufficient? >> Move FAQ.txt to docs/user/FAQ.txt. > > I think this should stay in the root, along with HISTORY, COPYING, and > README. I'm a little bit concerned about crowding the root directory. FAQ.txt IMO is a classical user doc file (we could link to docs/user/FAQ.txt from README.txt). (But I won't argue any further if you disagree.) >> Move 'Acknowledgements' from HISTORY.txt to docs/CREDITS.txt. > > ACK.txt, in the root. (Better name? How about THANKS.txt?) We're > not listing who did what, so "credits" isn't appropriate. If you really think that the name 'CREDITS.txt' is inappropriate (I'm not a native English speaker as you will already have noticed), THANKS.txt is IMO the best alternative. >> docs/notes/ideas.txt, > > Where is the text coming from? spec/notes.txt, spec/rst/alternatives.txt. The difference between ideas.txt and todo.txt is that in todo.txt only proposals are listed for which consensus on what exactly to implement exists. ideas.txt is for rough ideas or unsolved issues (i.e. without accepted and implementable solution). Some parts of alternatives.txt could also go into a file docs/dev/implemented.txt for already implemented things. (Any ideas for a more obvious and intuitive filename than implemented.txt?) >> Move 'Future Plans' from HISTORY.txt to docs/notes/ideas.txt or >> docs/notes/todo.txt. > > Perhaps make "Future Plans" into a "Priorities" section of > docs/dev/todo.txt. What about roughly sorting the things in todo.txt by priority? Having incorporated all your changes, the cleanup-outline currently looks like this: ------------------------------------------------------------------------ Move docs/* to docs/user/, move spec/ to docs/spec/. Move 'Acknowledgements' from HISTORY.txt to THANKS.txt. Create docs/dev/, split up spec/notes.txt to BUGS.txt, docs/dev/todo.txt, docs/dev/ideas.txt, docs/dev/policies.txt, docs/dev/website.txt, docs/dev/release.txt. Move spec/howto/ to docs/dev/howto/. Move 'Future Plans' from HISTORY.txt to docs/dev/ideas.txt or docs/dev/todo.txt. Split up spec/rst/alternatives.txt to docs/dev/todo.txt and docs/dev/ideas.txt (and maybe docs/dev/implemented.txt?). Add 'how to report bugs' to BUGS.txt. Add docs/index.txt. ------------------------------------------------------------------------ Did I miss anything? > There are some other repository cleanups I want to do, so we should > coordinate. I'm not going to touch anything before it is *absolutely* clear what to do. -- When replying to my email address, ensure that the mail header contains 'Felix Wiemann'. Please don't send unrequested mails > 64 KB. <http://www.ososo.de/> |
From: William D. <wi...@fl...> - 2004-05-13 21:27:09
|
Felix Wiemann <Fel...@gm...> writes: > David Goodger wrote: > >> Felix Wiemann wrote: >> >>> move licenses/ to docs/licenses/. >> >> No, leave licenses/ in the root. They're too important to bury. > > Really? Who reads licenses?! Don't you think adding a reference to the > docs/licenses/ directory and adjusting the existing links in COPYING.txt > is sufficient? I also think it's very important to let the licence on the top. When you install software (open or not) it must be the first things that you read, and accept or not to continue. -- William Dode - http://flibuste.net |
From: Felix W. <Fel...@gm...> - 2004-05-14 12:30:31
|
William Dode wrote: > Felix Wiemann writes: > >> David Goodger wrote: >> >>> No, leave licenses/ in the root. They're too important to bury. >> >> Really? Who reads licenses?! Don't you think adding a reference to the >> docs/licenses/ directory and adjusting the existing links in COPYING.txt >> is sufficient? > > I also think it's very important to let the licence on the top. When > you install software (open or not) it must be the first things that > you read, and accept or not to continue. At least in Germany (and I suspect it's the same in most other countries), you can't be restricted by a license you didn't explicitly agree to. Therefore the Docutils licenses only matter when you want to do things that are forbidden by usual copyright restrictions. Thus, when installing software as a user, I don't care the slightest bit about licenses[1]. Only before starting to modify a program, I have a quick look at the license. [1] As long as there is not an installation program asking me to agree. (Disclaimer: IANAL, so it might not be 100% accurate.) -- When replying to my email address, ensure that the mail header contains 'Felix Wiemann'. Please don't send unrequested mails > 64 KB. <http://www.ososo.de/> |
From: David G. <go...@py...> - 2004-05-15 03:35:03
|
Felix Wiemann wrote: > At least in Germany (and I suspect it's the same in most other > countries), you can't be restricted by a license you didn't > explicitly agree to. Therefore the Docutils licenses only matter > when you want to do things that are forbidden by usual copyright > restrictions. Since the Docutils licenses only *allow* the user to do things that are forbidden by usual copyright restrictions, I'm not worried. > Thus, when installing software as a user, I don't care the slightest > bit about licenses[1]. Only before starting to modify a program, I > have a quick look at the license. Licenses are central and of paramount importance to open source software. The licenses/ directory has to stay at the root. -- David Goodger |
From: Steve H. <sh...@ho...> - 2004-05-16 15:24:36
|
William Dode wrote: >Felix Wiemann <Fel...@gm...> writes: > > > >>David Goodger wrote: >> >> >> >>>Felix Wiemann wrote: >>> >>> >>> >>>>move licenses/ to docs/licenses/. >>>> >>>> >>>No, leave licenses/ in the root. They're too important to bury. >>> >>> >>Really? Who reads licenses?! Don't you think adding a reference to the >>docs/licenses/ directory and adjusting the existing links in COPYING.txt >>is sufficient? >> >> > >I also think it's very important to let the licence on the top. When >you install software (open or not) it must be the first things that you >read, and accept or not to continue. > > > In which case it should be the first thing presented *when the installer is run*, and its position in the distribution hirearchy matters less - even Windows users can search for "licennce" in their filestore if it matters before installation. Only $0.02. regards STvee |
From: David G. <go...@py...> - 2004-05-14 03:45:27
|
Felix Wiemann wrote: > Really? Who reads licenses?! Don't you think adding a reference to > the docs/licenses/ directory and adjusting the existing links in > COPYING.txt is sufficient? No. (Although I inferred a ";-)" there, I answered just to be sure.) > I'm a little bit concerned about crowding the root directory. I'm not. > FAQ.txt IMO is a classical user doc file (we could link to > docs/user/FAQ.txt from README.txt). (But I won't argue any further > if you disagree.) Call it an exception to the rule. I think/hope that a highly visible FAQ reduces the traffic to docutils-users. Reduced traffic may translate to more actual development (or at least, fewer excuses for not *doing* actual development). > If you really think that the name 'CREDITS.txt' is inappropriate > (I'm not a native English speaker as you will already have noticed), > THANKS.txt is IMO the best alternative. Agreed. ACK or ACKS is widely used, but is non-obvious. > The difference between ideas.txt and todo.txt is that in todo.txt > only proposals are listed for which consensus on what exactly to > implement exists. ideas.txt is for rough ideas or unsolved issues > (i.e. without accepted and implementable solution). I think one to-do list suffices for both purposes. I don't see the need for a separate ideas.txt. > Some parts of alternatives.txt could also go into a file > docs/dev/implemented.txt for already implemented things. I'd rather leave alternatives.txt alone, as docs/spec/rst/alternatives.txt. I just reorganized the topics of alternatives.txt into a structure that makes sense to me; please take a look. The only part I'd consider moving out of alternatives.txt is the "Doctree Representation of Transitions" section, because it's not reStructuredText-specific (the rest is). But until there's more than one topic, I wouldn't bother moving it. > What about roughly sorting the things in todo.txt by priority? In the past I've added "@" markers to show priority; the more @s, the higher the priority. I haven't kept up the practice, and I can't see myself sorting by priority either. A "Priorities" section may be feasible, but that's as far as I'll commit. > Having incorporated all your changes, the cleanup-outline currently > looks like this: > > -------------------------------------------------------------------- > Move docs/* to docs/user/, move spec/ to docs/spec/. Including spec/rst to docs/spec/rst, yes? But on further reflection, I realize that some of those documents are more reference materials than specifications. Specifically, directives.txt and interpreted.txt (which perhaps ought to be renamed to roles.txt?), are reference docs. Even reStructuredText.txt, the "reStructuredText Markup Specification", perhaps ought to be re-titled "The reStructuredText Markup Language". Some of the documents in spec/ are reference too: doctree.txt, transforms.txt, perhaps even docutils.dtd (and soextblx.dtd). Maybe spec/rst/introduction.txt ought to move to docs/user/rst/. And spec/rst/problems.txt and alternatives.txt may be better off in docs/dev/rst/. Perhaps everything in spec/ that's not reference ought to move to docs/dev/. > Move 'Acknowledgements' from HISTORY.txt to THANKS.txt. > > Create docs/dev/, split up spec/notes.txt to BUGS.txt, > docs/dev/todo.txt, docs/dev/ideas.txt, docs/dev/policies.txt, > docs/dev/website.txt, docs/dev/release.txt. No ideas.txt; not needed. > Move spec/howto/ to docs/dev/howto/. I think docs/howto/ may be better. > Move 'Future Plans' from HISTORY.txt to docs/dev/ideas.txt or > docs/dev/todo.txt. Move it into a new "Priorities" section of docs/dev/todo.txt. > Split up spec/rst/alternatives.txt to docs/dev/todo.txt and > docs/dev/ideas.txt (and maybe docs/dev/implemented.txt?). I think not. > Add 'how to report bugs' to BUGS.txt. > > Add docs/index.txt. > -------------------------------------------------------------------- Why don't you add this to the to-do list in spec/notes.txt? Then we can tweak it via CVS. We should still discuss it here though (unless nobody else cares, a not-improbable case ;-). -- David Goodger |
From: Felix W. <Fel...@gm...> - 2004-05-14 20:43:05
|
David Goodger wrote: > Felix Wiemann wrote: > >> Some parts of alternatives.txt could also go into a file >> docs/dev/implemented.txt for already implemented things. > > I'd rather leave alternatives.txt alone, as > docs/spec/rst/alternatives.txt. I just reorganized the topics of > alternatives.txt into a structure that makes sense to me; please take > a look. It looks better than before. However, it's still not clear to me what's the difference between alternatives.txt and "reStructuredText Parser" in notes.txt. >> Having incorporated all your changes, the cleanup-outline currently >> looks like this: >> >> -------------------------------------------------------------------- >> Move docs/* to docs/user/, move spec/ to docs/spec/. > > Including spec/rst to docs/spec/rst, yes? Sure. > But on further reflection, I realize that some of those documents are > more reference materials than specifications. Specifically, > directives.txt and interpreted.txt (which perhaps ought to be renamed > to roles.txt?), are reference docs. Aren't these references actually specifications? If not, what is the specification (e.g. for directives) then? > Even reStructuredText.txt, the "reStructuredText Markup > Specification", perhaps ought to be re-titled "The reStructuredText > Markup Language". I somehow seem to miss your point. In how far is it *not* a specification? >> Move 'Acknowledgements' from HISTORY.txt to THANKS.txt. >> >> Create docs/dev/, split up spec/notes.txt to BUGS.txt, >> docs/dev/todo.txt, docs/dev/ideas.txt, docs/dev/policies.txt, >> docs/dev/website.txt, docs/dev/release.txt. > > No ideas.txt; not needed. Why? IMO there's quite a big differene between the ready-to-implement things and the might-be-nice-to-have-something-like-that things. The documents are easily growing too big, which makes maintencance difficult. So I'd rather like having an ideas.txt. >> Move spec/howto/ to docs/dev/howto/. > > I think docs/howto/ may be better. Aren't those documents only *developer* HOWTOs? > [snip] > > Why don't you add this to the to-do list in spec/notes.txt? [x] Done. -- When replying to my email address, ensure that the mail header contains 'Felix Wiemann'. Please don't send unrequested mails > 64 KB. <http://www.ososo.de/> |
From: David G. <go...@py...> - 2004-05-15 03:41:22
|
[Felix Wiemann] > it's still not clear to me what's the difference between > alternatives.txt and "reStructuredText Parser" in notes.txt. The "reStructuredText Parser" section in notes.txt is a subsection of "To Do". They're things "to do" to the parser. Typically just short notes. The spec/rst/alternatives.txt file consists of summaries of discussions that led to decisions having to do with reStructuredText. It's for posterity, listing the rejected alternatives as well as the accepted and possibly implemented choice. Although some are "to do" (and linked to from the notes.txt to-do list), many are already done, or won't be done. As items from the to-do list are implemented, they are removed from spec/notes.txt. But spec/rst/alternatives.txt is a permanent record. [Felix Wiemann] >>> Move docs/* to docs/user/, move spec/ to docs/spec/. [David Goodger] >> Including spec/rst to docs/spec/rst, yes? > > Sure. > >> But on further reflection, I realize that some of those documents >> are more reference materials than specifications. Specifically, >> directives.txt and interpreted.txt (which perhaps ought to be >> renamed to roles.txt?), are reference docs. > > Aren't these references actually specifications? They began as specifications (plans for systems yet to be built), but have become reference material (documentation of systems already built, and read by end-users and library-user/developers as well as core-developers). Perhaps we ought to think of this reorganized docs/ directory in terms of the different groups of Docutils stakeholders: 1. End-users: users of reStructuredText and the Docutils tools. Many are not developers. 2. Library-user/developers: developers using Docutils as a library, programmers developing *with* Docutils. 3. Component-developers: those who implement application-specific components, directives, and/or roles, without contributing them back to Docutils. 4. Core-developers: developers of the Docutils codebase, participants in the Docutils project community. 5. Alternate-implementers: developers of alternate implementations of Docutils. (Any others?) There's a lot of overlap between these groups. Most (maybe all) core-developers, component-developers, library-user/developers, and alternate-implementers are also end-users. Core-developers are also library-user/developers, and may also be component-developers in other projects. Component-developers are also library-user/developers. I only know of one alternate-implementer: Mark Nodine (Perl). So the new directories to create are: * docs/user/: introductory/tutorial material for end-users * docs/dev/: for core-developers * docs/ref/: reference material for all groups * docs/howto/: for component-developers and core-developers * docs/lib/: API reference material for library-user/developers Added the "docs/lib/" directory, and will move spec/transforms.txt there. > If not, what is the specification (e.g. for directives) then? The specification for directive markup syntax is in spec/rst/reStructuredText.txt. The specifications for individual directives usually originate in the to-do list (from ideas on the mailing lists etc.). spec/rst/directives.txt documents existing directives (mostly; there are a few "to be implemented" sections there too). So I'd say it is reference material. >> Even reStructuredText.txt, the "reStructuredText Markup >> Specification", perhaps ought to be re-titled "The reStructuredText >> Markup Language". > > I somehow seem to miss your point. In how far is it *not* a > specification? It is a specification, but it's more than that. A specification would be used by core-developers and implementers, but not by end-users of the final implementation. Once it's used by end-users and library-user/developers, it has become reference material. Successful specs evolve into refs. >> No ideas.txt; not needed. > > Why? IMO there's quite a big differene between the > ready-to-implement things and the > might-be-nice-to-have-something-like-that things. I'd rather have one file, either with several sections ("To Do", "To Do?", "Not To Do?"), or simply individual indicators (like question marks on to-do items, as now). > The documents are easily growing too big, which makes maintencance > difficult. So I'd rather like having an ideas.txt. If the "definitely to do" items and "possibly to do" items are in separate files, I'm sure there will be duplication, because people (and by "people", I mean "I") won't check thoroughly. Maintaining a single source is more important than reducing individual file sizes. For now, let's leave it all in one file. >>> Move spec/howto/ to docs/dev/howto/. >> >> I think docs/howto/ may be better. > > Aren't those documents only *developer* HOWTOs? They're for component-developers and core-developers. I've updated the notes.txt file with my modifications to the plan. There are some questions there: - PEPs in ``spec/``? Move to ``docs/ref/`` or ``docs/dev/``? - Move ``alternatives.txt`` ... from ``spec/rst/`` to ``docs/dev/rst/``. (Move "Doctree Representation of Transitions" section elsewhere? Where?) - Move ... ``interpreted.txt`` from ``spec/rst/`` to ``docs/ref/rst/``. (Rename ``interpreted.txt`` to ``roles.txt``?) -- David Goodger |
From: Felix W. <Fel...@gm...> - 2004-05-15 14:44:14
|
David Goodger wrote: > [snip] First of all, thank you for your detailed explanations. > Perhaps we ought to think of this reorganized docs/ directory in terms > of the different groups of Docutils stakeholders: > > 1. End-users: users of reStructuredText and the Docutils tools. Many > are not developers. > > 2. Library-user/developers: developers using Docutils as a library, > programmers developing *with* Docutils. > > 3. Component-developers: those who implement application-specific > components, directives, and/or roles, without contributing them > back to Docutils. > > 4. Core-developers: developers of the Docutils codebase, participants > in the Docutils project community. > > 5. Alternate-implementers: developers of alternate implementations of > Docutils. Maybe between 1 and 2: Python-developers: developers utilizing reStructuredText or Docutils for documentating their source. All Python-developers are end-users, but not vice versa. > So the new directories to create are: > > * docs/user/: introductory/tutorial material for end-users > * docs/dev/: for core-developers > * docs/ref/: reference material for all groups > * docs/howto/: for component-developers and core-developers > * docs/lib/: API reference material for library-user/developers Maybe also docs/python/ for Python-developers? > I've updated the notes.txt file with my modifications to the plan. > There are some questions there: > > - PEPs in ``spec/``? Move to ``docs/ref/`` or ``docs/dev/``? PEP 258 to docs/lib/ (it's not a reference and it's not only relevant for core-developers). PEP 256, PEP 257, PEP 287 (and later Python source reader documentation) to docs/python/, see above. > - Move ``alternatives.txt`` ... from ``spec/rst/`` to > ``docs/dev/rst/``. (Move "Doctree Representation of Transitions" > section elsewhere? Where?) Am I right that it's actually only 'Internal Representation', 'Output' and 'Implementation Plan' which have to be moved? My ideas: 1. Leave it as is. These three sections don't hurt. 2. Or create a new file (docs/dev/lineblocks.txt) and add a link in alternatives.txt. 3. Or move docs/dev/rst/alternatives.txt to docs/dev/alternatives.txt, so it isn't reST-specific. > - Move ... ``interpreted.txt`` from ``spec/rst/`` to > ``docs/ref/rst/``. (Rename ``interpreted.txt`` to ``roles.txt``?) I think 'roles.txt' is better. -- When replying to my email address, ensure that the mail header contains 'Felix Wiemann'. Please don't send unrequested mails > 64 KB. <http://www.ososo.de/> |
From: David G. <go...@py...> - 2004-05-15 20:38:58
|
Felix Wiemann wrote: > Python-developers: developers utilizing reStructuredText or Docutils > for documentating their source. All Python-developers are > end-users, but not vice versa. I don't know if that warrants its own category. Aren't "Python developers using reStructuredText docstrings" just one case of end-users? > Maybe also docs/python/ for Python-developers? We can add it if it proves necessary. I don't see anything that needs to go there now. > PEP 258 to docs/lib/ (it's not a reference and it's not only > relevant for core-developers). I agree that PEP 258 is not only relevant to core-developers, but I think it is becoming (or *should* become) a reference. > PEP 256, PEP 257, PEP 287 (and later Python > source reader documentation) to docs/python/, see above. If we're going to move the PEPs anywhere, they should all go to the same place. If not /docs/ref/, how about /docs/peps/? >> - Move ``alternatives.txt`` ... from ``spec/rst/`` to >> ``docs/dev/rst/``. (Move "Doctree Representation of >> Transitions" section elsewhere? Where?) > > Am I right that it's actually only 'Internal Representation', > 'Output' and 'Implementation Plan' which have to be moved? No, those are unrelated; they're subsections of "Syntax for Line Blocks", which should remain in alternatives.txt. "Doctree Representation of Transitions" is a separate section. -- David Goodger |
From: Felix W. <Fel...@gm...> - 2004-05-16 13:51:25
|
David Goodger wrote: > If we're going to move the PEPs anywhere, they should all go to the > same place. If not /docs/ref/, how about /docs/peps/? docs/peps/ is good. Added to notes.txt. >>> - Move ``alternatives.txt`` ... from ``spec/rst/`` to >>> ``docs/dev/rst/``. (Move "Doctree Representation of >>> Transitions" section elsewhere? Where?) >> >> Am I right that it's actually only 'Internal Representation', >> 'Output' and 'Implementation Plan' which have to be moved? > > No, those are unrelated; Ummm. 8-) Anyway, the solution is probably the same: It doesn't hurt, so leave it as is, and as soon as there are more 'alternatives' that are not reST-specific, create a new document. Or straightly move docs/dev/rst/alternatives.txt to docs/dev/alternatives.txt, if you like that better. -- When replying to my email address, ensure that the mail header contains 'Felix Wiemann'. Please don't send unrequested mails > 64 KB. <http://www.ososo.de/> |
From: Felix W. <Fel...@gm...> - 2004-05-24 17:05:59
|
David Goodger wrote: > It would be useful to keep the CVS history of moved files. To do so, > we need to supply SourceForge with a script for modifying the Docutils > CVS repository > (http://sf.net/docman/display_doc.php?docid=768&group_id=1#repositoryrestructure). The following script works, as far as I could test it [1]: ------------------------------------------------------------------------------- #!/bin/sh cd /cvsroot/docutils/docutils/ set -e # Exit on error. # Ensure that we really are in the docutils module. test -d ./docs -a -d ./spec alias 'md=mkdir -v' alias 'mv=mv -v' md docs/user/ # introductory/tutorial material for end-users md docs/dev/ # for core-developers md docs/ref/ # reference material for all groups md docs/lib/ # API reference material for library-user/developers md docs/peps/ # Python Enhancement Proposals md docs/dev/rst/ md docs/ref/rst/ mv docs/config.txt,v docs/user/ mv docs/latex.txt,v docs/user/ mv docs/tools.txt,v docs/user/ mv docs/rst/ docs/user/ mv spec/howto/ docs/howto/ # for component-developers and core-developers mv spec/pysource.dtd,v docs/dev/ mv spec/pysource.txt,v docs/dev/ mv spec/semantics.txt,v docs/dev/ mv spec/doctree.txt,v docs/ref/ mv spec/docutils.dtd,v docs/ref/ mv spec/soextblx.dtd,v docs/ref/ mv spec/transforms.txt,v docs/lib/ mv spec/rst/alternatives.txt,v docs/dev/rst/ mv spec/rst/introduction.txt,v docs/dev/rst/ mv spec/rst/problems.txt,v docs/dev/rst/ mv spec/rst/reStructuredText.txt,v docs/ref/rst/ mv spec/rst/directives.txt,v docs/ref/rst/ mv spec/rst/interpreted.txt,v docs/ref/rst/roles.txt mv spec/pep-????.txt,v docs/peps/ echo Finished. ------------------------------------------------------------------------------- There are still the following issues: * docs/ref/rst/reStructuredText.txt has capital letters, which turns out to be bad e.g. when people start manually typing in URLs (e.g. from a treeware-magazine) and aren't aware of case-sensitiveness. Furthermore, it's incosistent, because AFAICS there are no other camel-case documents in the Docutils web-tree. What about renaming it to restructuredtext.txt (and creating a symlink on the webserver so that the old URL doesn't die)? * docs/lib/ only contains the file transforms.txt. Move it to docs/core/, so we don't need the docs/lib/ directory? > There are some other repository cleanups I want to do, so we should > coordinate. Do you already have scripts for those cleanups? ------------- Footnote [1]: Just for completeness, I tested it the following way, in case anyone cares: 1. Save my script as ``cleanup``. 2. Create a new, empty directory and cd into it. 3. Export docutils from CVS. 4. find -type f -exec mv -v {} {},v \; 5. cp docutils docutils.bak -r, so you won't need to re-export. 6. rm docutils -rf && cp docutils.bak/ docutils -r && cd docutils && cp ~/source/docutils/docutils/spec/cleanup . && ./cleanup && cd .. (Adjust path of cleanup-script as necessary, and repeat this step when you modified the cleanup-script.) -- When replying to my email address, ensure that the mail header contains 'Felix Wiemann'. Please don't send unrequested mails > 64 KB. <http://www.ososo.de/> |
From: David G. <go...@py...> - 2004-05-26 17:23:40
|
Felix Wiemann wrote: > The following script works, as far as I could test it [1]: Thanks. I checked it in to CVS (sandbox/davidg/infrastructure/cvs-reorg.sh), and made some changes. > There are still the following issues: > > * docs/ref/rst/reStructuredText.txt has capital letters, which turns > out to be bad We'll rename it, lowercase, with a symlink. > * docs/lib/ only contains the file transforms.txt. Move it to > docs/core/, so we don't need the docs/lib/ directory? Do you mean docs/dev/? I don't think it fits there. We'll put it in docs/ref/. >> There are some other repository cleanups I want to do, so we should >> coordinate. > > Do you already have scripts for those cleanups? Part of cvs-reorg.sh now. > Footnote [1]: > > Just for completeness, I tested it the following way, in case anyone > cares: I made you a project administrator (don't abuse it!), so you can download the repository tarball directly (http://cvs.sourceforge.net/cvstarballs/docutils-cvsroot.tar.bz2) and test on that. Details here: <https://sourceforge.net/project/admin/backup.php?group_id=38414>. -- David Goodger <http://python.net/~goodger> |
From: Felix W. <Fel...@gm...> - 2004-05-29 20:34:43
|
David Goodger wrote: > Felix Wiemann wrote: > >> The following script works, as far as I could test it [1]: > > Thanks. I checked it in to CVS > (sandbox/davidg/infrastructure/cvs-reorg.sh), and made some changes. I changed 'rm -r' to 'rm -rfv' in order to make it verbose and to make it not prompt on write-protected files (444). There was a 'rm -r /cvsroot/docutils/module' in the cleanup script. However, that directory doesn't exist. I changed it to 'modulename', which makes more sense to me. > I made you a project administrator (don't abuse it!), Thank you. > so you can download the repository tarball directly > (http://cvs.sourceforge.net/cvstarballs/docutils-cvsroot.tar.bz2) and > test on that. The cleanup-script seems to work correctly now. -- http://www.ososo.de/ |
From: David G. <go...@py...> - 2004-05-29 21:14:57
|
Felix Wiemann wrote: > The cleanup-script seems to work correctly now. Your changes look fine, thanks. -- David Goodger <http://python.net/~goodger> |
From: Felix W. <Fel...@gm...> - 2004-05-31 15:48:09
|
David Goodger wrote: > Felix Wiemann wrote: > >> The cleanup-script seems to work correctly now. > > Your changes look fine, thanks. After running the cleanup-script, the spec/ directory doesn't exist anymore. These are the contents of the docs/ directory: $ find docs | sed 's/,v//' docs docs/user docs/user/rst docs/user/rst/quickref.html docs/user/rst/quickstart.txt docs/user/rst/images docs/user/rst/images/ball1.gif docs/user/rst/images/biohazard.png docs/user/rst/images/title.png docs/user/rst/images/Attic docs/user/rst/images/Attic/biohazard.bmp docs/user/rst/images/Attic/biohazard.gif docs/user/config.txt docs/user/latex.txt docs/user/tools.txt docs/dev docs/dev/rst docs/dev/rst/alternatives.txt docs/dev/rst/problems.txt docs/dev/pysource.dtd docs/dev/pysource.txt docs/dev/semantics.txt docs/dev/todo.txt docs/ref docs/ref/rst docs/ref/rst/restructuredtext.txt docs/ref/rst/directives.txt docs/ref/rst/roles.txt docs/ref/rst/introduction.txt docs/ref/doctree.txt docs/ref/docutils.dtd docs/ref/soextblx.dtd docs/ref/transforms.txt docs/peps docs/peps/pep-0256.txt docs/peps/pep-0257.txt docs/peps/pep-0258.txt docs/peps/pep-0287.txt docs/howto docs/howto/rst-directives.txt docs/howto/i18n.txt docs/howto/rst-roles.txt Does anyone see something to improve? If not, I think you can go ahead, David, and send the script to the guys at SF. (Please announce it before, so that nobody is working on the docs during the restructuring process.) -- http://www.ososo.de/ |
From: Lele G. <le...@na...> - 2004-05-31 17:49:43
|
>>>>> "Felix" =3D=3D Felix Wiemann <Fel...@gm...> writes: Felix> Does anyone see something to improve? No, great work Felix&David! Just a doubt: did you try a "cvs update" in a working copy /after/ the repository cleanup? Is there anything special one should perform on his client side of story? thanx&bye, lele. --=20 nickname: Lele Gaifax | Quando vivr=C3=B2 di quello che ho pensato ieri real: Emanuele Gaifas | comincer=C3=B2 ad aver paura di chi mi copia. email: le...@se... | -- Fortunato Depero, 1929. |
From: Aahz <aa...@py...> - 2004-06-02 02:21:50
|
On Mon, May 31, 2004, Lele Gaifax wrote: > > Just a doubt: did you try a "cvs update" in a working copy /after/ the > repository cleanup? Is there anything special one should perform on > his client side of story? Make sure that your .cvsrc has the following lines; the last one is critical for this operation: cvs -z3 diff -c update -dP (The Python dev docs contain this info, IIRC.) -- Aahz (aa...@py...) <*> http://www.pythoncraft.com/ "as long as we like the same operating system, things are cool." --piranha |
From: David G. <go...@py...> - 2004-06-02 14:34:15
|
Aahz wrote: > Make sure that your .cvsrc has the following lines; Good point. Wrote it up and added it to the project policies: <http://docutils.sf.net/spec/notes.html#cvs-startup-file>. -- David Goodger <http://python.net/~goodger> |
From: David G. <go...@py...> - 2004-05-31 18:36:44
|
> docs/user/latex.txt I'm wondering, should this file be here? It isn't really user documentation, is it? Perhaps it should be docs/dev/latex.txt. There is some user documentation for rst2latex.py (http://docutils.sf.net/docs/tools.html#rst2latex-py), which probably needs updating. -- David Goodger <http://python.net/~goodger> |