Opened at 2009-02-14T15:03:11Z

Closed at 2011-09-25T03:17:58Z

#627 closed enhancement (fixed)

formatting of NEWS file

Reported by: kpreid Owned by: somebody
Priority: minor Milestone: 1.9.0
Component: website Version: 1.3.0
Keywords: NEWS docs Cc: kpreid
Launchpad Bug:

Description

I was reading ​http://allmydata.org/trac/tahoe/browser/NEWS to learn about Tahoe 1.3.0, and I read down to "* Release 1.1.0 (2008-06-11)" before noticing that I had reached the end of the 1.3.0 section.

I suggest that the publicly-anounced version of NEWS should be reformatted to convert the *-outline into headings, say in a HTML document.

Here's a quick hack to perform that conversion: 

perl -wne '
  BEGIN { print "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01//EN\" \"http://www.w3.org/TR/html4/strict.dtd\"><html>" }
  s/&/&amp;/g; 
  s/</&lt;/g; 
  if (/^(.*?)\s*-\*-.*?-\*-$/) { print "<title>$1</title><pre>" } 
  elsif (/^(\*+) (.+)$/) { my $l = length $1; print "</pre><h$l>$2</h$l><pre>" } 
  else { print }
  END { print "</pre></html>" }
' NEWS > NEWS.html; open NEWS.html

Change History (8)

comment:1 Changed at 2009-02-15T21:02:45Z by warner

  • Version changed from unknown to 1.3.0

Just to confirm: you were reading that NEWS file in your browser, through the Trac source-code browser link that you mentioned, right? (as opposed to reading it out of a local source tree, or some other HTML page).

The NEWS file as checked into the source tree (which that link points to) is formatted to be read by someone who has downloaded the source tree (it's basically in emacs outline-mode format). We should probably create an HTML form of it specifically for the website, rather than pointing at the source-code browser's version. We should also label it as being for a specific version (i.e. NEWS-1.3.0.html instead of NEWS.html), since it won't be automatically updated.

comment:2 Changed at 2009-02-17T02:22:54Z by kpreid

I think whether it's local is irrelevant: what about someone who has downloaded the source tree and doesn't use emacs?

But yes, I was reading it from the URL given above, which I got from the release announcement e-mail.

comment:3 Changed at 2009-06-19T21:51:15Z by kpreid

  • Cc kpreid added

comment:4 follow-up: Changed at 2009-12-04T07:55:37Z by warner

  • Keywords docs added

Let's add a step to the release process, in which we create an HTML version of the NEWS file and add it to the source tree (in NEWS.html), copy it to the website, and reference it in the release announcement. The NEWS.html file should include a note that points to NEWS (the non-html form) as the canonical source. After release, we should remove the NEWS.html from the tree, or establish a convention that we always update NEWS.html in the same commit that touches NEWS.

comment:5 Changed at 2009-12-04T17:04:27Z by zooko

Sounds fine to me.

comment:6 in reply to: ↑ 4 Changed at 2010-12-12T02:06:07Z by davidsarah

Replying to warner:

Let's add a step to the release process, in which we create an HTML version of the NEWS file and add it to the source tree (in NEWS.html), copy it to the website, and reference it in the release announcement. The NEWS.html file should include a note that points to NEWS (the non-html form) as the canonical source. After release, we should remove the NEWS.html from the tree, or establish a convention that we always update NEWS.html in the same commit that touches NEWS.

I'd prefer to convert NEWS to reStructuredText, than to have both .txt and .html versions of it.

Note that additional line breaks between versions were added to NEWS in [4857/trunk#file4]. As it stands, I don't think it's hard to read.

comment:7 Changed at 2010-12-12T03:24:36Z by zooko

  • Summary changed from NEWS version breaks are hard to spot to formatting of NEWS file

Yes, let's convert source:NEWS to rst!

comment:8 Changed at 2011-09-25T03:17:58Z by davidsarah

  • Milestone changed from undecided to 1.9.0
  • Resolution set to fixed
  • Status changed from new to closed

This was fixed in a817163cc698316d.

Note: See TracTickets for help on using tickets.