From owner-freebsd-doc  Thu Oct 26 15:42:44 2000
Delivered-To: freebsd-doc@freebsd.org
Received: from nothing-going-on.demon.co.uk (nothing-going-on.demon.co.uk [193.237.89.66])
	by hub.freebsd.org (Postfix) with ESMTP
	id 9471237B4C5; Thu, 26 Oct 2000 15:42:40 -0700 (PDT)
Received: (from nik@localhost)
	by nothing-going-on.demon.co.uk (8.11.0/8.11.0) id e9QLqOw15313;
	Thu, 26 Oct 2000 22:52:24 +0100 (BST)
	(envelope-from nik)
Date: Thu, 26 Oct 2000 22:52:23 +0100
From: Nik Clayton <nik@freebsd.org>
To: "Bruce A. Mah" <bmah@freebsd.org>
Cc: freebsd-doc@freebsd.org
Subject: Re: HARDWARE.TXT and RELNOTES.TXT
Message-ID: <20001026225223.A14836@canyon.nothing-going-on.org>
References: <200010261915.e9QJFep73565@bmah-freebsd-0.cisco.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
User-Agent: Mutt/1.2.5i
In-Reply-To: <200010261915.e9QJFep73565@bmah-freebsd-0.cisco.com>; from bmah@freebsd.org on Thu, Oct 26, 2000 at 12:15:40PM -0700
Organization: FreeBSD Project <URL:http://www.freebsd.org/>
Sender: owner-freebsd-doc@FreeBSD.ORG
Precedence: bulk
X-Loop: FreeBSD.org

Hi Bruce,

On Thu, Oct 26, 2000 at 12:15:40PM -0700, Bruce A. Mah wrote:
> Then I could build appropriate outputs with:
> 
> 	% cpp < relnotes.txt1 -Dalpha_docs > alpha/RELNOTES.TXT
> 	% cpp < relnotes.txt1 -Dia64_docs > ia64/RELNOTES.TXT
> 
> I've generated window manager configs like this for years, but to do
> this for documentation seems like a real hack.  However, I was wondering
> if we could do something like this with DocBook to generate the release
> notes?

Yes.  What you want are called "Marked sections".  See the 
tutorials/docproj-primer/ on the website, section 3.8 to be precise.

> Pros:
> 
> 1.  We would be able to collapse several (which depends on the number of
> architectures we support) files that need to be edited regularly down to
> a constant number (hardware list and release notes).
> 
> 2.  We would be able to generate release notes in PDF, PS, HTML, etc.
> 
> Cons:
> 
> 1.  I'm not sure how to do this in DocBook.
> 
> 2.  We would need to make the DocBook toolchain part of "make release".
> (Well, in a sense it is already, but in addition to having the Handbook
> and FAQ depend on the toolchain's presence, we'd also make the release
> notes dependent on this too.  I don't think this is a Good Thing (TM).)

Generating plain text and HTML versions of the release notes wouldn't
require anything that we don't already need when doing "make release".
 
> 3.  Doing release notes in DocBook might "raise the bar" to people
> committing their own release notes.

Hmm.  The amount of DocBook that the release notes are likely to use should
take less than five minutes for someone to pick up with no prior experience.
Worst case, patches are submitted to you for inclusion. . .

:-)

N
-- 
Internet connection, $19.95 a month.  Computer, $799.95.  Modem, $149.95.
Telephone line, $24.95 a month.  Software, free.  USENET transmission,
hundreds if not thousands of dollars.  Thinking before posting, priceless.
Somethings in life you can't buy.  For everything else, there's MasterCard.
  -- Graham Reed, in the Scary Devil Monastery


To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message