From: SourceForge.net <no...@so...> - 2006-03-23 14:39:52
|
Feature Requests item #1456993, was opened at 2006-03-23 22:39 Message generated for change (Tracker Item Submitted) made by Item Submitter You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=422033&aid=1456993&group_id=38414 Please note that this message will contain a full copy of the comment thread, including the initial issue submission, for this request, not just the latest update. Category: None Group: None Status: Open Resolution: None Priority: 5 Submitted By: Paul Wise (pabs3) Assigned to: Nobody/Anonymous (nobody) Summary: please include rst2man/etc Initial Comment: It would be nice if you could include rst2man from the experimental code tarball (docutils-sandbox-snapshot.tgz) in the main distribution. There are some other nice things in there too that could go into the main distribution. ---------------------------------------------------------------------- You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=422033&aid=1456993&group_id=38414 |
From: <gr...@us...> - 2006-03-26 11:31:57
|
Hi i would do it, taking paul as customer. any objections cheers -- |
From: David G. <go...@py...> - 2006-03-26 15:59:05
Attachments:
signature.asc
|
[gr...@us...] > i would do it, taking paul as customer. >=20 > any objections Please develop it either in your sandbox initially, or in a branch. You'll need to move over to a branch eventually to integrate it into the core. Docs and tests will be necessary. See http://docutils.sourceforge.net/docs/dev/policies.html#review-criteria and the "Check-Ins" section following. --=20 David Goodger <http://python.net/~goodger> |
From: <gr...@us...> - 2006-03-26 20:58:09
|
On Sun, 26 Mar 2006, David Goodger wrote: > [gr...@us...] >> i would do it, taking paul as customer. >> >> any objections > > Please develop it either in your sandbox initially, or in a branch. it is in my sandbox and some people seam to use it, without complain. i will try to get real feedback, if it is positive enough, i think it should go into the main trunk, to lower the usage hurdle. > You'll need to move over to a branch eventually to integrate it into > the core. eventually, but i dont see a reason, as it is only an addition and no modification for already present things. > Docs and tests will be necessary. See > http://docutils.sourceforge.net/docs/dev/policies.html#review-criteria > and the "Check-Ins" section following. i will start (after the "customers" reply) with the documentation, the tool is already present it just requires a note that it is in the sandbox yet. cheers -- |
From: David G. <go...@py...> - 2006-03-26 23:46:24
Attachments:
signature.asc
|
[gr...@us...] > i will try to get real feedback, if it is positive enough, i think > it should go into the main trunk, to lower the usage hurdle. I agree that it should go into the trunk core when it's ready, but I don't think it's ready yet. >> You'll need to move over to a branch eventually to integrate it >> into the core. > > eventually, but i dont see a reason, as it is only an addition and > no modification for already present things. You will need to integrate the writer, add tests & docs, and the code at present needs a lot of work. It's not even clear what ManPageWriter.py produces; the module doc string doesn't say (nroff? groff? text? HTML?). The code seems to need a lot of work; there seems to be a lot of unimplemented constructs and junk code. IOW the reason for a branch is because the man-page writer is not ready to be added to the core/trunk yet. Using a branch allows everyone to try out the changes in the core/trunk context, without messing up the trunk. --=20 David Goodger <http://python.net/~goodger> |
From: <gr...@us...> - 2006-03-27 08:42:51
|
On Sun, 26 Mar 2006, David Goodger wrote: > [gr...@us...] >> i will try to get real feedback, if it is positive enough, i think >> it should go into the main trunk, to lower the usage hurdle. > > I agree that it should go into the trunk core when it's ready, but I > don't think it's ready yet. > >>> You'll need to move over to a branch eventually to integrate it >>> into the core. >> >> eventually, but i dont see a reason, as it is only an addition and >> no modification for already present things. > > You will need to integrate the writer, add tests & docs, and the code > at present needs a lot of work. It's not even clear what > ManPageWriter.py produces; the module doc string doesn't say (nroff? > groff? text? HTML?). the module docstring does not say what it produces, so what will a ManPageWriter produce ? but you are correct it should and will be more specific. but manpage is really very spcific to me OTOH for macusers (i dont mean you, but in general) it means nothing. > The code seems to need a lot of work; there > seems to be a lot of unimplemented constructs and junk code. i dont code to fill specs, that is out of my time posibility, i code for usage and it usually works. this means the manpage writer should be capable to produce man.1 not docutils/test.man. i heard there is some table (tbl) support in manpages but havent seen a manpage with a table yet. and most important would be to get the minimal roff-macroset, so that manpages are processable everywhere. > IOW the reason for a branch is because the man-page writer is not > ready to be added to the core/trunk yet. Using a branch allows > everyone to try out the changes in the core/trunk context, without > messing up the trunk. using a branch allows every developer to try out, but no user. cheers and thanks for the feedback -- |
From: David G. <go...@py...> - 2006-03-28 00:52:18
Attachments:
signature.asc
|
[gr...@us...] > the module docstring does not say what it produces, so what will a > ManPageWriter produce ? but you are correct it should and will be > more specific. but manpage is really very spcific to me OTOH for > macusers (i dont mean you, but in general) it means nothing. "Man" means nothing to most Windows users, and to a growing number of Linux users too. > i dont code to fill specs, that is out of my time posibility, i code > for usage and it usually works. this means the manpage writer should > be capable to produce man.1 not docutils/test.man. Sorry, but that's not good enough for the core. See http://docutils.sourceforge.net/docs/dev/policies.html#check-ins for a list of minimal criteria. In particular, "reasonably complete": * _`Reasonably complete` means that the code must handle all input. Here "handle" means that no input can cause the code to fail (cause an exception, or silently and incorrectly produce nothing). "Reasonably complete" does not mean "finished" (no work left to be done). For example, a writer must handle every standard element from the Docutils document model; for unimplemented elements, it must *at the very least* warn that "Output for element X is not yet implemented in writer Y". Currently, this command: man.py ../../docutils/docs/user/rst/demo.txt demo.out crashes with the following output: NotImplementedError: Examples of Syntax Constructs =2E.. which was not very useful. I had to pass --traceback to find out that the unimplemented element was a subtitle. It *is* acceptable for the writer to produce a warning like: Warning: Element "subtitle" not supported in manual pages. (The warning should both be emitted to stderr and be visible in the document.) But it's *not* acceptable for it to crash like that. > using a branch allows every developer to try out, but no user. First open it up to developers for polishing, and then to users. Developers can handle crashes, and even fix things; users can only complain. We want to minimize the need for complaints by fixing whatever we can, first. If you're willing to get it to that point, great, I'm happy to help. If not, the code will stay in your sandbox. --=20 David Goodger <http://python.net/~goodger> |
From: <gr...@us...> - 2006-03-28 08:24:58
|
On Mon, 27 Mar 2006, David Goodger wrote: *big snip* i already got your point years ago. it fails in one point: adding one new command does not harm any old code, but helps for the one case where it is used even if only implemented in a small portion. there were several times i had to fix some sandbox things because the api changed, what do you expect you would need to fix if i add some new writer. commiting to the main trunk does not hit any normal user, only snapshot users, but makes it easier for developers to just run the command, without the need to checkout a separate branch. anyway the project is not urgent, so i could start a sandbox with manpage-writer or make a branch. but in a sandbox it is harder to reuse the testing environment and one needs a setup.py, if others should be able to test it in a user environment, for development i never call setup.py. this is better in a branch. without a leadcustomer i tend to making a sandbox: * manpage-writer * pydoc-writer >> using a branch allows every developer to try out, but no user. > > First open it up to developers for polishing, and then to users. > Developers can handle crashes, and even fix things; users can only > complain. We want to minimize the need for complaints by fixing > whatever we can, first. If you're willing to get it to that point, > great, I'm happy to help. If not, the code will stay in your sandbox. cheers -- |
From: Felix W. <Fel...@gm...> - 2006-04-01 16:55:47
|
gr...@us... wrote: > it fails in one point: adding one new command does not harm any old > code, but helps for the one case where it is used even if only > implemented in a small portion. Nope. As a user, if I get a command "rst2man.py", I want it to work in all cases. I don't want to rely on the fact that it works and later be badly surprised by feature-incompleteness, crashes, and similar funny things. > there were several times i had to fix some sandbox things because the > api changed, what do you expect you would need to fix if i add some > new writer. Well, we'd have to keep the man page writer up-to-date. That can be difficult if the code isn't clean, so I don't want to commit to it as long as it isn't complete, reasonably bug-free, tested, and documented. > commiting to the main trunk does not hit any normal user, only > snapshot users, Snapshot users *are* normal users. (We encourage users to use the snapshot on the Docutils homepage!) Also, if we allow code unsuitable for normal users in the trunk, we cannot follow the "release early, release often" policy anymore. I want the trunk to be releasable at any time. > but makes it easier for developers to just run the > command, without the need to checkout a separate branch. Well, I have a complete checkout of the whole repository (trunk, branches, and tags). And you can always use "svn switch". > anyway the project is not urgent, so i could start a sandbox with > manpage-writer or make a branch. Unless you expect to get the writer feature-complete quickly, I'd recommend using the sandbox because a branch would diverge from the trunk over time. > but in a sandbox it is harder to reuse the testing environment Now this is a problem. Should we maybe move the tests into the main docutils directory, so that you can say "from docutils.test import DocutilsTestSupport"? I'm not sure... > and one needs a setup.py, Mh, yes. The bad thing is that we don't have a plugin mechanism yet, otherwise you could just drop the package in ~/.docutils/plugins/. >>> using a branch allows every developer to try out, but no user. We can implement daily (or hourly) snapshots for branches if the need arises. -- For private mail please ensure that the header contains 'Felix Wiemann'. "the number of contributors [...] is strongly and inversely correlated with the number of hoops each project makes a contributing user go through." -- ESR |
From: <gr...@us...> - 2006-04-01 20:44:12
|
On Sat, 1 Apr 2006, Felix Wiemann wrote: > gr...@us... wrote: > >> it fails in one point: adding one new command does not harm any old >> code, but helps for the one case where it is used even if only >> implemented in a small portion. > > Nope. As a user, if I get a command "rst2man.py", I want it to work in > all cases. I don't want to rely on the fact that it works and later be > badly surprised by feature-incompleteness, crashes, and similar funny > things. all cases, means all cases for a manpage not all cases for reST. man does not support images, and i still wait for one using tables. and if there is one user (not me) using it for his manpage, it is complete for this user, so what ? >> there were several times i had to fix some sandbox things because the >> api changed, what do you expect you would need to fix if i add some >> new writer. > > Well, we'd have to keep the man page writer up-to-date. That can be > difficult if the code isn't clean, so I don't want to commit to it as > long as it isn't complete, reasonably bug-free, tested, and documented. i did keep the latexwriter uptodate, so why do you imply i wouldnt do it with a manpage writer. >> commiting to the main trunk does not hit any normal user, only >> snapshot users, > > Snapshot users *are* normal users. (We encourage users to use the > snapshot on the Docutils homepage!) > > Also, if we allow code unsuitable for normal users in the trunk, we > cannot follow the "release early, release often" policy anymore. I want > the trunk to be releasable at any time. 1. who says i code unusable for normal users ? 2. i am for "release early, release often" therefore i would put it into main trunk early, not late. the problem starts here >> but makes it easier for developers to just run the >> command, without the need to checkout a separate branch. > > Well, I have a complete checkout of the whole repository (trunk, > branches, and tags). And you can always use "svn switch". does alltest.py work over branches ? getting into >> anyway the project is not urgent, so i could start a sandbox with >> manpage-writer or make a branch. > > Unless you expect to get the writer feature-complete quickly, I'd > recommend using the sandbox because a branch would diverge from the > trunk over time. correct >> but in a sandbox it is harder to reuse the testing environment > > Now this is a problem. Should we maybe move the tests into the main > docutils directory, so that you can say "from docutils.test import > DocutilsTestSupport"? I'm not sure... now you see, add to it that it is in a drifting branch >> and one needs a setup.py, > > Mh, yes. The bad thing is that we don't have a plugin mechanism yet, > otherwise you could just drop the package in ~/.docutils/plugins/. and that users cant use it >>>> using a branch allows every developer to try out, but no user. > > We can implement daily (or hourly) snapshots for branches if the need > arises. (not really, if there is a user complain/feature request i usually mail the source and commit.) and we need more snapshots you have a little much effort for ... uhm nothing, the only thing that can happen, is that some user tries the rst2man.py and it does not work, now there are complains on rst2latex too should i remove it therefore ? i understand your and davids arguments, but they are somehow hindering contributing. did anyone recognize that i am the only one that took a writer out of the sandbox. on users people keep asking for stuff that is in the sandbox, but out of sight. cheers -- |
From: David G. <go...@py...> - 2006-04-01 23:03:12
Attachments:
signature.asc
|
[gr...@us...] >>> it fails in one point: adding one new command does not harm any >>> old code, but helps for the one case where it is used even if only >>> implemented in a small portion. [Felix Wiemann] >> Nope. As a user, if I get a command "rst2man.py", I want it to >> work in all cases. I don't want to rely on the fact that it works >> and later be badly surprised by feature-incompleteness, crashes, >> and similar funny things. [gr...@us...] > all cases, means all cases for a manpage not all cases for reST. > man does not support images, and i still wait for one using tables. But any reST is possible as input, and should not make the writer crash. Crashing on an image (or *any* element) is not acceptable. Once the code is in good shape, usable, documented, tested, and reasonably complete (as per http://docutils.sf.net/docs/dev/policies.html#check-ins), it can be considered for the core. Until then, it can stay in your sandbox. > and if there is one user (not me) using it for his manpage, it is > complete for this user, so what ? So it doesn't go into the core, that's what. If you understand this policy, as you said you do, stop arguing about it in this way. It's extremely annoying and counterproductive. I'm sorry but I don't understand a lot of what you wrote in the rest of your message. And I don't want to argue. Perhaps you and Felix can discuss this further in your native German. --=20 David Goodger <http://python.net/~goodger> |
From: Mikolaj M. <mi...@wp...> - 2006-04-02 20:23:35
|
gr...@us... scripsit: > all cases, means all cases for a manpage not all cases for reST. > man does not support images, and i still wait for one using tables. In such case warning should be issued, or completely ignore it with documentation what will be ignored. Hardcore solution is to implement some sort of ASCII-art generator. m. -- LaTeX + Vim = http://vim-latex.sourceforge.net/ Vim Universal Templates: http://vim.sf.net/script.php?script_id=1078 vim.pl - http://skawina.eu.org/mikolaj CLEWN - http://clewn.sf.net |