From: David G. <go...@py...> - 2003-08-17 14:57:07
|
Beni Cherniavsky wrote: > It's obvious that a user's file should override the system-wide > file. But why should it override the local per-directory config? Well, it was obvious to me at the time. The user's ~/.docutils is specific to one user, whereas the project's ./docutils.conf may be shared by many users. Individual (specific) preferences ought to override project (general) preferences. I can see your point, but I wonder if it isn't simply the individual user's responsibility to ensure they don't abuse their ~/.docutils file. Before we make such a change, I'd like to be completely sure it's correct. I don't want to have to reverse the change later. > This means that one can't use user's file for defaults he likes for > most projects (the way the system-wide file would be used when users > agree on the same dafaults) - eny setting made there overrides all > settings (except command-line settings but that's awkward). Have you actually been bitten by this? Can you provide any real-life examples? > The only rationale I can see it a user downloading complete > directories with reST sources and config files, and wishing to > override some settings globally, e.g. for his accessibility. > However this scenario is much less probable than processing one's > own files, in various projects, which frequently involves > per-project settings. Can you justify this position? > The current behavior makes no sense to me and I believe this should > be changed. Does anybody use ~/.docutils? (I don't.) How do you use it? -- David Goodger http://starship.python.net/~goodger For hire: http://starship.python.net/~goodger/cv Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) |
From: Beni C. <cb...@us...> - 2003-09-11 10:07:00
|
David Goodger wrote on 2003-08-19: > Hi Beni, > > I'm almost finished reorganizing the config file system for > flexibility (multiple sections, dynamically interpreted). I'll > probably check in all the changes in the next few days. After that, a > patch to support a DOCUTILSCONFIG envar would be welcome! > Implemented, commited. It doesn't break any test and passes my manual tests for the new feature. I'd have to think a bit how to implement a test for it (os.environ manipulation with try..finally-guarded reversal, I guess, dirty...). [Yes, I know it's better to write the test even before the code, I'm gradually learning TDD but so far I've been only doing simple doctests.] P.S. what happens to the config stuff on Windows and Mac? I made DOCUTILSCONFIG `os.pathsep`-separated (colon means drive letters on Windows and directories(?) on Mac). ``~/.docutils`` will work on Windows for the rare users that set %HOME% but will never work on Mac, according to the `os.path.expanduser` docs. I'm also not sure that ``./docutils.conf`` works on Mac (I think it should be ``:docutils.conf``). Could some Mac user step in and tell us what's the right thing to do there? P.P.S. forget about my scenarios for big projects having to override DOCUTILSCONFIG, I didn't notice docutils looks for ``./docutils.conf`` in the current working directory, which solves most such needs. -- Beni Cherniavsky <cb...@us...> |
From: Beni C. <cb...@us...> - 2003-09-11 15:06:17
|
Beni Cherniavsky wrote on 2003-09-11: > David Goodger wrote on 2003-08-19: > > > After that, a patch to support a DOCUTILSCONFIG envar would be > > welcome! > > > Implemented, commited. It doesn't break any test and passes my manual > tests for the new feature. No, it didn't. Shame on me, stupid bug on my first commit! What passed was an older version on which I last did ``./install.py``. Now I symlinked my machine's ``site-packages/docutils`` to my development tree... > I'd have to think a bit how to implement a test for it (os.environ > manipulation with try..finally-guarded reversal, I guess, dirty...). > [Yes, I know it's better to write the test even before the code, I'm > gradually learning TDD but so far I've been only doing simple > doctests.] > I simply subclassed existing config tests to also be run through DOCUTILSCONFIG (see commit log). > P.S. what happens to the config stuff on Windows and Mac? I made > DOCUTILSCONFIG `os.pathsep`-separated (colon means drive letters on > Windows and directories(?) on Mac). ``~/.docutils`` will work on > Windows for the rare users that set %HOME% but will never work on > Mac, according to the `os.path.expanduser` docs. I'm also not sure > that ``./docutils.conf`` works on Mac (I think it should be > ``:docutils.conf``). Could some Mac user step in and tell us what's > the right thing to do there? > Still an open issue... Should I ask on docutils-users for wider audience? -- Beni Cherniavsky <cb...@us...> |
From: David G. <go...@py...> - 2003-09-11 22:44:56
|
Beni Cherniavsky wrote: > Implemented, commited. Cool, thanks. > P.S. what happens to the config stuff on Windows and Mac? I made > DOCUTILSCONFIG `os.pathsep`-separated (colon means drive letters on > Windows and directories(?) on Mac). ``~/.docutils`` will work on > Windows for the rare users that set %HOME% but will never work on > Mac, according to the `os.path.expanduser` docs. I suspect that the docs are out of date, since Mac OS X has full BSD underpinnings. Macs must support both ":" and "/" as directory separators, but I don't know the details on context (command-line or GUI). Since Docutils is usually a command-line beast, I'd expect "/" to win. > I'm also not sure that ``./docutils.conf`` works on Mac (I think it > should be ``:docutils.conf``). Could some Mac user step in and tell > us what's the right thing to do there? Works for me, with Mac OS 10.2.x. "./docutils.conf" works fine. I don't have access to a Mac right now, so I can't experiment. > Still an open issue... Should I ask on docutils-users for wider > audience? Sure, go ahead. -- David Goodger http://starship.python.net/~goodger For hire: http://starship.python.net/~goodger/cv Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) |
From: Beni C. <cb...@te...> - 2003-08-17 15:38:15
|
David Goodger wrote on 2003-08-17: > Beni Cherniavsky wrote: > > It's obvious that a user's file should override the system-wide > > file. But why should it override the local per-directory config? > > Well, it was obvious to me at the time. The user's ~/.docutils is > specific to one user, whereas the project's ./docutils.conf may be > shared by many users. Individual (specific) preferences ought to > override project (general) preferences. > I see your scenario now. There is a project shared by many users (do they put the processed output at the common dir? Or are these local copies of the project?). The problem is that they won't necessarily use use the same overrides for all projects, will they? If you imagine putting something in ``~/.docutils``, running docutils and removing it, an environment variable pointing to a file of overrides would be much better. > I can see your point, but I wonder if it isn't simply the individual > user's responsibility to ensure they don't abuse their ~/.docutils > file. Before we make such a change, I'd like to be completely sure > it's correct. I don't want to have to reverse the change later. > Sure. I still don't quite understand what's the non-abusive way to use `~/.docutils` you imagine. > > This means that one can't use user's file for defaults he likes for > > most projects (the way the system-wide file would be used when users > > agree on the same dafaults) - eny setting made there overrides all > > settings (except command-line settings but that's awkward). > > Have you actually been bitten by this? Can you provide any real-life > examples? > > Does anybody use ~/.docutils? (I don't.) How do you use it? > source-link: 1 datestamp: %Y-%m-%d %H:%M UTC generator: 1 exit-level: warning stylesheet: /home/beni/docutils/stylesheets/default.css embed-stylesheet: 1 These are settings I like to use but I must be able to set at least stylesheet and embed-stylesheet per-project. For now I'll just move them into `/etc/docutils.conf` but that's only acceptable on my home machine, where I happen to be the only user of docutils. -- Beni Cherniavsky <cb...@tx...> |
From: David G. <go...@py...> - 2003-08-17 18:00:47
|
Beni Cherniavsky wrote: > I see your scenario now. There is a project shared by many users Yes. > (do they put the processed output at the common dir? Or are these > local copies of the project?). Up to the project members. > The problem is that they won't necessarily > use use the same overrides for all projects, will they? This is the first time I've heard of someone having any trouble with the setup, so I can't say. > If you imagine putting something in ``~/.docutils``, running > docutils and removing it, an environment variable pointing to a file > of overrides would be much better. I don't follow. > I still don't quite understand what's the non-abusive way to > use `~/.docutils` you imagine. Use it less, or not at all. Put all settings in the project-specific docutils.conf. Don't put per-project settings in ~/.docutils. >> Does anybody use ~/.docutils? (I don't.) How do you use it? > > source-link: 1 > datestamp: %Y-%m-%d %H:%M UTC > generator: 1 > exit-level: warning > stylesheet: /home/beni/docutils/stylesheets/default.css > embed-stylesheet: 1 > > These are settings I like to use but I must be able to set at least > stylesheet and embed-stylesheet per-project. So set them per-project. I intended ~/.docutils for minor individual preferences, like footnote-references and exit-level. Perhaps the best solution would be to remove support for ~/.docutils altogether? I'm not averse to changing the way config files work, but there needs to be a concensus that a change is necessary and what that change should be. I'd really like to hear what others have to say; how people use config files, and the impact of any change. Here's an idea: perhaps the set of config files could be configurable. The default set (/etc/docutils.conf, ./docutils.conf, ~/.docutils) could be overridden with a "config-files" setting (note: wouldn't work on the command line). Your /etc/docutils.conf could contain config-files: ~/.docutils, ./docutils.conf The first file couldn't be overridden, but if it's higher-priority (i.e. it should override) it could be tacked on to the end of the list. -- David Goodger http://starship.python.net/~goodger For hire: http://starship.python.net/~goodger/cv Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) |
From: Beni C. <cb...@te...> - 2003-08-17 19:41:37
|
David Goodger wrote on 2003-08-17: > Beni Cherniavsky wrote: > > > I still don't quite understand what's the non-abusive way to > > use `~/.docutils` you imagine. > > Use it less, or not at all. Put all settings in the project-specific > docutils.conf. Don't put per-project settings in ~/.docutils. > > >> Does anybody use ~/.docutils? (I don't.) How do you use it? > > > > source-link: 1 > > datestamp: %Y-%m-%d %H:%M UTC > > generator: 1 > > exit-level: warning > > stylesheet: /home/beni/docutils/stylesheets/default.css > > embed-stylesheet: 1 > > > > These are settings I like to use but I must be able to set at least > > stylesheet and embed-stylesheet per-project. > > So set them per-project. These are all things I do in all my projects, so being lazy, I wanted them as defaults. OTOH, using local `docutils.conf` files would allow others who download my projects to see the same settings, so I should probably switch. I can symlink them when I don't need exceptions... > I intended ~/.docutils for minor individual preferences, like > footnote-references and exit-level. Perhaps the best solution would > be to remove support for ~/.docutils altogether? > Unix tradition says that for any config file in /etc, there should be a personal dotfile allowing the user to achieve the same effects when he dislikes the sysadmin's choice. The current scheme allows to sysadmin only to provide defaults and the user only to provide global overrides. This tying makes little sense. If there is usage for both defaults and overrides, provide all 4 combinations (although allowing the sysadmin to make global overrides is perhaps stupid). > I'm not averse to changing the way config files work, but there needs > to be a concensus that a change is necessary and what that change > should be. I'd really like to hear what others have to say; how > people use config files, and the impact of any change. > > Here's an idea: perhaps the set of config files could be configurable. > The default set (/etc/docutils.conf, ./docutils.conf, ~/.docutils) > could be overridden with a "config-files" setting (note: wouldn't work > on the command line). Your /etc/docutils.conf could contain > > config-files: ~/.docutils, ./docutils.conf > > The first file couldn't be overridden, but if it's higher-priority > (i.e. it should override) it could be tacked on to the end of the list. > And where the current file's setting go? The difference between the first file and the rest is non-intuitive. If you want both weaker and stronger "includes", I think two different options would be better. Even better would be apply these "include"s in the order encountered (it seems that `ConfigParser` could handle that). So my `~/.docutils` could go along these lines:: # Defaults stylesheet: /home/beni/docutils/stylesheets/default.css embed-stylesheet: 1 config-file: ./docutils.conf # Overrides exit-level: warning However the sysadmin would want `./docutils.conf` to be found even without me mentioning it in `~/.docutils`, so he would include both in `/etc/docutils.conf` anyway. But then my include becomes redudant. So the sysadmin should probably include two of personal dotfiles anyway, one before `./docutils.conf` and one after it. So I'm not sure such complexity is needed. Just hardcode such two dotfiles into docutils, e.g.: - `/etd/docutils.conf` - `~/.docutils-defaults` - `./docutils.conf - `~/.docutils` -- Beni Cherniavsky <cb...@tx...> |
From: David G. <go...@py...> - 2003-08-17 22:03:15
|
Beni Cherniavsky wrote: > These are all things I do in all my projects, so being lazy, I > wanted them as defaults. Could this be the source of the misunderstanding? You mention "defaults and overrides". There's no such distinction. There are system-wide settings, project-specific settings, and user-specific settings. Later-applied settings override earlier ones. Putting so many settings in the last config file (~/.docutils) doesn't work, so don't do that. The only "defaults" are those hard-coded into the source. > OTOH, using local `docutils.conf` files would allow others who > download my projects to see the same settings, so I should probably > switch. I think so. > Unix tradition says that for any config file in /etc, there should > be a personal dotfile allowing the user to achieve the same effects > when he dislikes the sysadmin's choice. And that's what we have, plus project-specific settings. Perhaps the complication lies is in having project-specific settings at all? ;-) > The current scheme allows to sysadmin only to provide defaults and > the user only to provide global overrides. The user provides user-specific settings, not global. > This tying makes little sense. Do you know of a system that handles config settings better? It would be nice to have a model to emulate. > And where the current file's setting go? What do you mean? > The difference between the first file and the rest is non-intuitive. There's no difference. The "config-files" setting could be specified in any of them. The greatest control is gained by specifying it in /etc/docutils.conf, that's all. > If you want both weaker and stronger "includes", I don't, *you* do. ;-) > I think two different options would be better. Such as? > Even better would be apply these "include"s in the order encountered > (it seems that `ConfigParser` could handle that). Not without some significant support. ConfigParser is pretty simple. > So my `~/.docutils` could go along these lines:: > > # Defaults > stylesheet: /home/beni/docutils/stylesheets/default.css > embed-stylesheet: 1 > > config-file: ./docutils.conf > > # Overrides > exit-level: warning So you want the "config-file" setting to do the equivalent of a #include? That would be tricky. That's not what I'm talking about. This is how I see a "config-files" setting working: The default list of config files is ['/etc/docutils.conf', './docutils.conf', '~/.docutils']. These are visited one at a time, in order. If a "config-files" setting is encountered in any of those places, the remainder of the default list of files is replaced by the list specified. For example, if "config-files: path/docutils.conf" is found in ./docutils.conf, it will replace ~/.docutils, which will *not* be read. > However the sysadmin would want `./docutils.conf` to be found even > without me mentioning it in `~/.docutils`, so he would include both > in `/etc/docutils.conf` anyway. The sysadmin wouldn't have to do that. The default list of config files would be used if no "config-files" setting is encountered. > But then my include becomes redudant. No it doesn't. The order of parsing config files is significant. Your "config-files" setting would force ./docutils.conf to be re-read after ~/.docutils, making its priority higher. > So the sysadmin should probably include two of personal dotfiles > anyway, one before `./docutils.conf` and one after it. S/he could, if that's the system policy. > So I'm not sure such complexity is needed. Just hardcode such two > dotfiles into docutils, e.g.: > > - `/etd/docutils.conf` > - `~/.docutils-defaults` > - `./docutils.conf > - `~/.docutils` That would be easier. But would it satisfy everyone? I don't like the name though; they're not "defaults" and "overrides", but "pre-project-settings" and "post-project-settings". -- David Goodger http://starship.python.net/~goodger For hire: http://starship.python.net/~goodger/cv Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) |
From: Beni C. <cb...@te...> - 2003-08-18 10:04:12
|
David Goodger wrote on 2003-08-17: > Beni Cherniavsky wrote: > > These are all things I do in all my projects, so being lazy, I > > wanted them as defaults. > > Could this be the source of the misunderstanding? You mention > "defaults and overrides". There's no such distinction. There are > system-wide settings, project-specific settings, and user-specific > settings. Later-applied settings override earlier ones. Putting so > many settings in the last config file (~/.docutils) doesn't work, so > don't do that. > That's right. I'm afraid I clouded my ideas with too many terminalogy shifts. > > Unix tradition says that for any config file in /etc, there should > > be a personal dotfile allowing the user to achieve the same effects > > when he dislikes the sysadmin's choice. > > And that's what we have, plus project-specific settings. No. The administrator can only set settings that are overriden by per-project local settings (that's what I called "defaults"). The user can only set settings that are applied after per-project settings (that's what I called "overrides"). > Perhaps the complication lies is in having project-specific settings > at all? ;-) > No, no, no. Project-specific settings are very powerful, user/system-specific settings are a convenience feature only. > > The current scheme allows to sysadmin only to provide defaults and > > the user only to provide global overrides. > > The user provides user-specific settings, not global. > I meant that they apply to all projects, after their settings. While that might be good for someone, I happen to mainly want settings that apply to all projects before them. [skip too complex include-like system, forget it ;] A simpler idea: let an environment variable (`DOCUTILS_CONF`?) contain a colon-separated list of files to read. It can default to the current scheme. I would add another dotfile before per-project settings in my login script. Big projects can modify the variable in their makefiles to allow sharing common options between many directories... OTOH, if the user has arranged settings both before and after per-porject settings, there is no easy way to modify the environment variable in a per-porject makefile, while respecting both (you can only easily add entries at either end of the list). > > So I'm not sure such complexity is needed. Just hardcode such two > > dotfiles into docutils, e.g.: > > > > - `/etd/docutils.conf` > > - `~/.docutils-defaults` > > - `./docutils.conf > > - `~/.docutils` > > That would be easier. But would it satisfy everyone? I don't like > the name though; they're not "defaults" and "overrides", but > "pre-project-settings" and "post-project-settings". > Yes, your names are better. -- Beni Cherniavsky <cb...@tx...> |
From: David G. <go...@py...> - 2003-08-19 03:55:24
|
Beni Cherniavsky wrote: > A simpler idea: let an environment variable (`DOCUTILS_CONF`?) > contain a colon-separated list of files to read. It can default to > the current scheme. I would add another dotfile before per-project > settings in my login script. Big projects can modify the variable > in their makefiles to allow sharing common options between many > directories... That sounds reasonable. It would allow the user to add config files and specify their order, but it would also allow the user to disable any or all standard config files, including the project-specific one (./docutils.conf). > OTOH, if the user has arranged settings both before and after > per-porject settings, there is no easy way to modify the environment > variable in a per-porject makefile, while respecting both (you can > only easily add entries at either end of the list). Would that be a problem? Do you realistically envisage a project that will need such dynamic modifications to the envar? It's the same issue with other environment variables like PATH, and people work around them just fine. This issue seems to only apply to your setup (you're the first one to raise the issue), so if an envar solves the issue for you, why complicate matters with improbable "what ifs"? >> I don't like the name though; they're not "defaults" and >> "overrides", but "pre-project-settings" and >> "post-project-settings". >> > Yes, your names are better. But too long. Better to leave the naming up to the individual project/user in the environment variable. So you could use "~/.docutils-defaults" if that makes sense to you. -- David Goodger http://starship.python.net/~goodger For hire: http://starship.python.net/~goodger/cv Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) |
From: Beni C. <cb...@te...> - 2003-08-19 06:38:46
|
David Goodger wrote on 2003-08-18: > Beni Cherniavsky wrote: > > A simpler idea: let an environment variable (`DOCUTILS_CONF`?) > > contain a colon-separated list of files to read. It can default to > > the current scheme. I would add another dotfile before per-project > > settings in my login script. Big projects can modify the variable > > in their makefiles to allow sharing common options between many > > directories... > > That sounds reasonable. It would allow the user to add config files > and specify their order, but it would also allow the user to disable > any or all standard config files, including the project-specific one > (./docutils.conf). > > > OTOH, if the user has arranged settings both before and after > > per-porject settings, there is no easy way to modify the environment > > variable in a per-porject makefile, while respecting both (you can > > only easily add entries at either end of the list). > > Would that be a problem? Do you realistically envisage a project that > will need such dynamic modifications to the envar? It's the same > issue with other environment variables like PATH, and people work > around them just fine. This issue seems to only apply to your setup > (you're the first one to raise the issue), so if an envar solves the > issue for you, why complicate matters with improbable "what ifs"? > Err, yes, I'm inventing complex scenarios when nobody but me needs half-complex ones ;-). -- Beni Cherniavsky <cb...@tx...> |
From: Magnus <ma...@th...> - 2003-08-19 09:09:37
|
At 23:54 2003-08-18 -0400, David Goodger wrote: >Beni Cherniavsky wrote: > > A simpler idea: let an environment variable (`DOCUTILS_CONF`?) > > contain a colon-separated list of files to read. It can default to > > the current scheme. I would add another dotfile before per-project > > settings in my login script. Big projects can modify the variable > > in their makefiles to allow sharing common options between many > > directories... > >That sounds reasonable. It would allow the user to add config files >and specify their order, but it would also allow the user to disable >any or all standard config files, including the project-specific one >(./docutils.conf). Maybe I missed something in Beni's mail, but how would the project specific config file get into this scheme? A relative path and then go to a certain directory before running the command? -- Magnus Lycka (It's really Lyckå), ma...@th... Thinkware AB, Sweden, www.thinkware.se I code Python ~ The Agile Programming Language |
From: David G. <go...@py...> - 2003-08-19 12:50:00
|
Magnus Lyckå wrote: > Maybe I missed something in Beni's mail, but how would the project > specific config file get into this scheme? A relative path and then > go to a certain directory before running the command? A relative path in the envar, which Docutils would interpret relative to the current working directory. The envar equivalent of the current standard would be: DOCUTILSCONFIG=/etc/docutils.conf:./docutils.conf:~/.docutils The envar would have to be handled carefully (relative paths, tilde expansion), but it shouldn't be an issue. -- David Goodger http://starship.python.net/~goodger For hire: http://starship.python.net/~goodger/cv Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) |