Opened at 2011-05-10T20:56:49Z
Closed at 2011-05-17T01:18:37Z
#1400 closed enhancement (fixed)
format NEWS to restructuredtext?
| Reported by: | zooko | Owned by: | marlowe |
|---|---|---|---|
| Priority: | major | Milestone: | 1.9.0 |
| Component: | documentation | Version: | 1.8.2 |
| Keywords: | docs | Cc: | warner |
| Launchpad Bug: |
Description
Restructuredtext is a good standard for formatting text files. We've been converting all of our documents to restructuredtext (most of them were in plaintext and a few were in HTML). .rst also allows generation of .html (or .pdf, etc.) if we want. Should we format source:NEWS in restructuredtext? It is pretty close already. Here is, attached, the result of running rst2html on the current NEWS file.
Attachments (10)
Change History (20)
Changed at 2011-05-10T20:57:19Z by zooko
comment:1 Changed at 2011-05-10T20:59:55Z by zooko
- Owner changed from somebody to warner
comment:2 Changed at 2011-05-10T22:07:12Z by warner
yeah, I guess I'm ok with that. I've been keeping NEWS in outline-mode (to match what most old GNU projects do, like emacs and gcc), but I guess .rst would be fine too. If trac will auto-format .rst files, then I'm +0 on it, as that could be kinda nice.
comment:3 Changed at 2011-05-10T23:41:27Z by zooko
Here it is with everything newer than about 1.5.0 converted. I'm still working on it. Run "rst2html" to see the nicer-looking rendering (which is roughly what trac is going to show). Also there is rst2pdf for when you want to print it out and deliver to the doorstep of each person who lives in your town.
Changed at 2011-05-10T23:41:42Z by zooko
comment:4 Changed at 2011-05-11T02:00:12Z by zooko
Here is a more complete version: attachment:NEWS-rst, and the resulting html: attachment:NEWS-rst.html I don't understand why "Bugfixes and improvements" in 1.7.1 is formatted differently than "Bugfixes and improvements" in 1.7.0.
Changed at 2011-05-11T02:00:38Z by zooko
Changed at 2011-05-11T02:00:45Z by zooko
Changed at 2011-05-11T02:32:32Z by marlowe
Wish I could say what I fixed, but I deleted the section and reentered it by hand. However, it resolves the issue.
Changed at 2011-05-11T16:59:55Z by zooko
comment:5 Changed at 2011-05-11T17:01:59Z by zooko
marlowe: run darcs mv NEWS NEWS.rst (if you are using darcs), and then look at attachment:NEWS.rst. I hyperlinkified all the ticket numbers down to release 1.5.0 or so. Would you please hyperlinkify the rest of them and also any other references in the file (such as "see the architecture.txt document [3] for details")?
comment:6 Changed at 2011-05-11T17:02:08Z by zooko
- Owner changed from warner to marlowe
Changed at 2011-05-13T22:05:57Z by zooko
comment:7 Changed at 2011-05-13T22:09:59Z by zooko
marlowe: please use attachment:NEWS-restification-1.darcs.patch .
It includes file renaming and changing other files which refer to NEWS to have them refer to NEWS.rst instead.
To apply this patch download it and run darcs apply NEWS-restification-1.darcs.patch. Get a clean darcs repository (e.g. darcs get --lazy http://tahoe-lafs.org/source/tahoe-lafs/trunk) and cd into the resulting directory (named trunk) and then run the darcs apply command. If you have already made edits to NEWS then please apply them to the resulting file (either manually or by using patch).
Make sense?
Changed at 2011-05-16T23:14:52Z by marlowe
Updated NEWS.rst to include links for tickets and updated .rst files
comment:8 Changed at 2011-05-16T23:36:04Z by marlowe
- Keywords review-needed added
comment:9 Changed at 2011-05-17T00:12:41Z by davidsarah
- Keywords reviewed added; review-needed removed
Couple of nitpicks:
- The ".. -*- coding: utf-8 -*-" isn't necessary since the file doesn't contain any non-ASCII characters. (As far as I can tell, there is no way to formally specify the encoding of an .rst file, although some parsers may assume UTF-8 anyway. Unicode characters can be included using substitutions as described here.)
- Around line 1468, there seems to be a minor formatting glitch (the spacing between "size" and "distribution").
Otherwise +1, and thanks.
comment:10 Changed at 2011-05-17T01:18:37Z by davidsarah
- Keywords reviewed removed
- Milestone changed from undecided to 1.9.0
- Resolution set to fixed
- Status changed from new to closed
Applied at a817163cc698316d, with a correction in abe961ec78aff7ef.
(The link [2] in relnotes.txt will need to be changed again for the next release; in the meantime it should continue to refer to NEWS@5000 to avoid a broken link.)
Assigning to Brian to see if he is < 0 on this.
(I would like to do it, so say "-1" if you don't want me to.)