From: <gr...@us...> - 2004-06-01 06:09:44
|
On Mon, 31 May 2004, David Goodger wrote: > > 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. no this is user documentation (devs should look at the code *and* at this document). docs/latex.txt has definately information for the user, how to influence latex (what to put into stylesheet). problems and workarounds if any. tools.html i thought is only for the options not for the usage. cheers -- BINGO: professionally create virtual services |
From: David G. <go...@py...> - 2004-06-01 15:00:43
|
[David Goodger] >>> docs/user/latex.txt >> >> I'm wondering, should this file be here? [gr...@us...] > no this is user documentation (devs should look at the code *and* at > this document). > > docs/latex.txt has definately information for the user, how to > influence latex (what to put into stylesheet). problems and > workarounds if any. I'm not a LaTeX user, so maybe I'm wrong, but a lot of docs/latex.txt reads like developer documentation to me. Imagine a newbie Docutils user who wants to use it for LaTeX (and imagine the user is a LaTeX newbie too); is docs/latex.txt useful to them? It's very confusing to me. > tools.html i thought is only for the options not for the usage. docs/config.txt is for the settings/options. docs/tools.txt describes the front-end tools and their usage. It's fine to have a separate document for the rst2latex.py tool, but if it's user documentation it should be written for users, not for developers. If it's for developers, it should be moved (or split). The title, "Docutils LaTeX Writer", indicates that it's for developers (end-users don't care about Writers). Suggestions: * The document title should be changed (perhaps "Generating LaTeX with Docutils", or "Docutils rst2latex.py"). * The header of the first column of table under "Options", "Setting/Config Entry", is misleading, and should be changed. * How do we set these options? In the stylesheet? There ought to be examples of usage (how to set the stylesheet), and a link to the default stylesheet. * Perhaps the "Problems" section of the document should be split out into a developer document. * Is <http://docutils.sf.net/docs/tools.html#rst2latex-py> up to date? -- David Goodger <http://python.net/~goodger> |
From: David G. <go...@py...> - 2004-06-02 15:13:36
|
Felix Wiemann wrote: > 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.) Sent to SF (https://sf.net/tracker/index.php?func=detail&aid=965087&group_id=1&atid=200001). I don't know how long it will be before they run the script, but when they do, it should be an almost instantaneous change. I doubt anyone will be adversely affected, but please remember to run "cvs update" before any checkins. -- David Goodger <http://python.net/~goodger> |
From: David G. <go...@py...> - 2004-06-02 20:58:36
|
SourceForge staff have run the cvs-reorg.sh script. I'm fixing the web site now, and I've installed a .htaccess file to redirect from old to new URLs. Please let me know if any links break, or if you have any other issues. I'm working on a docs/index.txt file. I'd appreciate help updating the links in all the documents. Please run "cvs update" on your working directories. You'll have to manually delete the spec/ and docs/rst/ subdirectories. Anonymous CVS access is having trouble. I hope it's just a synchronization issue; if so, it will clear up soon. I'll keep the snapshots up to date manually until it works again. -- David Goodger <http://python.net/~goodger> |
From: David G. <go...@py...> - 2004-06-03 14:47:07
|
I've checked in the first round of changes and new files after the docs reorganization. Major changes: * new "Docutils Project Documentation Overview": http://docutils.sf.net/docs/index.html * To-Do list is now separate: http://docutils.sf.net/docs/dev/todo.html * new "Docutils Project Policies": http://docutils.sf.net/docs/dev/policies.html * new "Docutils Web Site": http://docutils.sf.net/docs/dev/website.html * new "Docutils Release Procedure": http://docutils.sf.net/docs/dev/release.html * new "Docutils Bugs": http://docutils.sf.net/BUGS.html * new "Acknowledgements": http://docutils.sf.net/THANKS.html * "Docutils History" is much leaner: http://docutils.sf.net/HISTORY.html * removed redundant info from the web site main page; now links to doc overview: http://docutils.sf.net/#documentation Still to do: go through all the docs (including under web/) and code, and update links. .htaccess redirects are in place, but that's stopgap measure at best. I must concentrate on other work for a while, so I invite anyone interested to take on part of this. -- David Goodger <http://python.net/~goodger> |
From: Felix W. <Fel...@gm...> - 2004-06-07 11:52:00
|
The references in the code are now updated, too. I am confident that I caught most references, so I updated HISTORY.txt. I didn't touch the sandboxes, and neither am I going to, because I don't want to mess with other people's (semi-)private code. -- 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-06-07 12:47:23
|
Felix Wiemann wrote: > The references in the code are now updated, too. > I am confident that I caught most references, so > I updated HISTORY.txt. There were lots of files to go through, and lots of changes to make. But going through the files, you caught a lot more than the many changes due to the doc cleanup: a variety of broken links and more. Thanks, Felix! -- David Goodger |
From: David G. <go...@py...> - 2004-05-31 18:03:40
|
Lele Gaifax wrote: > No, great work Felix&David! > > Just a doubt: did you try a "cvs update" in a working copy > /after/ the repository cleanup? Your praise & doubt are a bit premature. The repository cleanup hasn't actually happened yet. We've just written a script to do it, which we'll submit to SourceForge. > Is there anything special one should perform on > his client side of story? I don't think so. After a "cvs update", new files & directories should appear. Old files & directories may be left behind though. We shall see. -- David Goodger <http://python.net/~goodger> |
From: Lele G. <le...@na...> - 2004-05-31 18:46:40
|
>>>>> "David" =3D=3D David Goodger <go...@py...> writes: David> Lele Gaifax wrote: >> No, great work Felix&David! Just a doubt: did you try a "cvs >> update" in a working copy /after/ the repository cleanup? David> Your praise & doubt are a bit premature. The repository David> cleanup hasn't actually happened yet. We've just written a David> script to do it, which we'll submit to SourceForge. No, it is not! I do follow the ML, so I know what's going on. When it will happen does not change my taste of something I wished from the beginning :) ciao, 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: Felix W. <Fel...@gm...> - 2004-05-31 19:25:58
|
David Goodger wrote: >> docs/user/latex.txt > > I'm wondering, should this file be here? It isn't really user > documentation, is it? Part of it is user documentation (IMO most things before the 'problems' section), so it should be put into the user-doc directory. Developers are assumed to have read the user documentation. > Perhaps it should be docs/dev/latex.txt. I don't actually care *too* much. Engelbert? -- http://www.ososo.de/ |
From: <gr...@us...> - 2004-06-01 06:14:21
|
On Mon, 31 May 2004, Felix Wiemann wrote: > David Goodger wrote: > > >> docs/user/latex.txt > > > > I'm wondering, should this file be here? It isn't really user > > documentation, is it? > > Part of it is user documentation (IMO most things before the 'problems' > section), so it should be put into the user-doc directory. Developers > are assumed to have read the user documentation. why do you want user unclear of problems that will/could arise. > > Perhaps it should be docs/dev/latex.txt. > > I don't actually care *too* much. Engelbert? it is user doc. but i dont care because even felix didnt read it before plaguing me with his bugreports. cheers -- BINGO: professionally create virtual services |
From: Felix W. <Fel...@gm...> - 2004-06-03 13:06:42
|
David Goodger wrote: > I'm not a LaTeX user, so maybe I'm wrong, but a lot of docs/latex.txt > reads like developer documentation to me. That's probably because LaTeX is pretty complex; LaTeX documentation always looks that way. :) > Imagine a newbie Docutils user who wants to use it for LaTeX (and > imagine the user is a LaTeX newbie too); is docs/latex.txt useful to > them? Not too much. But it's certainly useful to those users who know LaTeX. > * The document title should be changed (perhaps "Generating LaTeX with > Docutils", or "Docutils rst2latex.py"). IMO "Generating LaTeX [code? files?] with Docutils" is good. > * How do we set these options? In the stylesheet? Sure. $ cat ~/tmp/stylesheet.tex \geometry{landscape} $ rst2latex.py --stylesheet ~/tmp/stylesheet.tex source.txt dest.tex > There ought to be examples of usage (how to set the stylesheet), > and a link to the default stylesheet. Engelbert, what do you think? > * Perhaps the "Problems" section of the document should be split out > into a developer document. I think Engelbert is right that the user should know of these problems. > * Is <http://docutils.sf.net/docs/tools.html#rst2latex-py> up to date? "The generated file includes a file style.tex, which allows the inclusion of special packages or changes to settings made in the header." does not seem correct to me (it isn't included automatically). But maybe I'm missing something. -- 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/> |