#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:


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)

NEWS.html (75.5 KB) - added by zooko at 2011-05-10T20:57:19Z.
NEWS (61.7 KB) - added by zooko at 2011-05-10T23:41:42Z.
NEWS-rst (63.5 KB) - added by zooko at 2011-05-11T02:00:38Z.
NEWS-rst.html (77.4 KB) - added by zooko at 2011-05-11T02:00:45Z.
NEWS-rst.2 (63.5 KB) - added by marlowe at 2011-05-11T02:32:32Z.
Wish I could say what I fixed, but I deleted the section and reentered it by hand. However, it resolves the issue.
NEWS-rst.2.html (77.0 KB) - added by marlowe at 2011-05-11T02:32:59Z.
The corresponding HTML file
NEWS.rst (70.8 KB) - added by zooko at 2011-05-11T16:59:55Z.
NEWS-restification-1.darcs.patch (139.6 KB) - added by zooko at 2011-05-13T22:05:57Z.
NEWS.2.rst (72.2 KB) - added by marlowe at 2011-05-16T23:14:52Z.
Updated NEWS.rst to include links for tickets and updated .rst files
NEWS.3.rst (72.1 KB) - added by marlowe at 2011-05-17T00:28:41Z.
Updated to resolved davidsarah's comments

Download all attachments as: .zip

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

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.)

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-11T02:32:59Z by marlowe

The corresponding HTML file

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

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.

Changed at 2011-05-17T00:28:41Z by marlowe

Updated to resolved davidsarah's comments

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.)

Note: See TracTickets for help on using tickets.