Date: Tue, 10 Jul 2001 13:57:53 +0100 From: Nik Clayton <nik@freebsd.org> To: Dima Dorfman <dima@unixfreak.org> Cc: Nik Clayton <nik@freebsd.org>, doc@freebsd.org Subject: Re: State of the Handbook Message-ID: <20010710135753.G16152@clan.nothing-going-on.org> In-Reply-To: <20010710113247.A2B863E28@bazooka.unixfreak.org>; from dima@unixfreak.org on Tue, Jul 10, 2001 at 04:32:47AM -0700 References: <20010710114034.E16152@clan.nothing-going-on.org> <20010710113247.A2B863E28@bazooka.unixfreak.org>
next in thread | previous in thread | raw e-mail | index | archive | help
--reI/iBAAp9kzkmX4 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Tue, Jul 10, 2001 at 04:32:47AM -0700, Dima Dorfman wrote: > Nik Clayton <nik@freebsd.org> writes: > > 2. Supplement the ASCII art with images. > >=20 > > Something else on WRS' todo list, although it doesn't prevent anyo= ne > > else with an artistic bent from picking some of the existing ASCII= art > > and producing images for it as well. WRS expect to have this done= by > > the end of August. >=20 > Do we have a mechanism so that we can keep the ASCII art and display > it where necessary? I.e., I'd rather not see the ASCII art thrown > away; not everybody wants to start a graphics-capable browser to read > the docs (I know I don't). Yes we do. See section 4.2.6 of the primer. We've previously talked about adding another format to the set that's generated; html-no-images (or similar). That's trivial to generate (since we already generate it in order to produce the plain text version of the docs). However, it brings up an additional issue -- currently, the output formats are all produced in the 'current' directory. This works OK for the formats that we have, since none of them have filenames that 'collide' with one another. It won't work with a hypothetical 'html-no-images' format. The likes of 'book.html' is perfectly legitimate in this format, which would collide with the files generated by the 'html' format. It's also feasible that people would want an 'html-split-no-images' format as well, the output files for which would collide with the output from the 'html-split' format. > > 3. Stylesheet and wordlist > >=20 > > We're quite inconsistent about the use and spelling of terms, > > and the stylesheet for authors is quite small. We're talking to > > O'Reilly about the licensing behind their stylesheet and wordlist > > at http://www.oreilly.com/oreilly/author/stylesheet.html and the > > possiblity of making this available to all open source documentati= on > > projects (probably as a guide). >=20 > I'm not quite sure what this is. Is this a stylesheet as in a DSSSL > stylesheet? =20 No. I'm thinking more in terms Strunk and White, the Chicago Manual of Style, and so on. Not that we need to be that comprehensive, but we probably need to a little more comprehensive than the current few paragraphs in the primer. > It seems that the link above is what we need; it talks > about how certain things should be written, etc. Do we need a license > to look at it? Or am I missing something? We're not the only documentation project that would benefit from this sort of thing. If a number of projects adopt the O'Reilly style then perhaps O'Reilly could help out -- set up a mailing list where notifications of changes to the style or wordlist are sent to, so that each project 'tracking' the O'Reilly work is alerted, and so on. =20 > > 5. Integration of Randy Pratt's install guide to replace much of the > > existing material in chapter 2. >=20 > I haven't read Randy Pratt's install guide,=20 http://people.freebsd.org/~rpratt/ > but just about anything is > better than the outdated stuff we have! Unless somebody else (e.g., > Randy Pratt) wants to do this, I will (or I'll check in someone else's > patches to do it). Randy (and Murray) are working on it at the moment I believe. > > 6. Licensing > >=20 > > Some sections of the Handbook are under inconsistent copyrights > > and licenses. I (nik) would like the entirety of the Handbook (and > > indeed, the FreeBSD docs as a whole) to be available under a consi= stent > > license, with the copyright transferred to a single entity -- > > probably the FreeBSD Foundation. Where sections of the Handbook do > > not do this, we will be contacting the original authors to ask them > > whether they would consider relicensing their work. If they are n= ot > > happy for this to happen then we will need to replace the content > > with text under a 'free-er' license. >=20 > I don't see a problem with individual copyright holders as long as > they're using a reasonable license. =20 We still have to define 'reasonable' in this context. There are a half dozen or so 'documentation' licenses out there; the GNU Free Documentation License, the Open Content License, and whatever licenses people like Apple are using for Darwin. Then there's the BSD-style license I (fairly abitrarily) slapped on the Handbook. I'm also uncertain how things like the copyright notice on chapter 13, or appendix F, 4,3,=20 I guess it's not so much copyright as license that I'm concerned about. > Their name in the copyright > notice is also a form of credit; not everybody thinks it's appropriate > to clutter the main text with "I rewrote this" type of attributions. You snipped the bit where we discussed attribution. Any thoughts? > > 8. Removing some content to other documents. > >=20 > > As a minimum, we expect to move the following chapters and/or > > sections > >=20 > > Source Tree Guidelines and Policies -> Developer's Handbook > > Kernel Debugging -> Developer's Handbook >=20 > Perhaps now's a good time to bring this up: what exactly is the > Developer's Handbook supposed to be? =20 <snip> I'll leave this to Murray and/or Asmodai, as the Dev. Handbook is their initiative. > > Bibliography -> Book in its own right = (?) >=20 > Erm, the bibliography should really stay with the document (book) that > it goes along with. However, the Handbook's Bibliography section > should be spelled Other Links. I was envisioning a 'meta' bibliography. Books/articles that need a bibliography include this one, and the stylesheets can be configured to only include information about books that are referenced in the main text. At the same time, we could then have a separate 'bibliography' book that just contained details about every other document listed in the bibliographies of all the other books. > > 9. Adding additional content > >=20 > > Chern Lee is working on a chapter for "Configuration and Tuning", > > and Chris Shumway is working on extending the X11 chapter. >=20 > Yes! This is exactly what we need more of. We have plenty of people > doing the minor whitespace/spelling fixes, but we've been down on new > or updated content lately (and I'm not helping :-/). >=20 > And while WRS is sponsering this stuff, perhaps they can get another > computer to act as www.freebsd.org; having freefall do that isn't good > for security. Oh, and maybe they can help fix the "broken Handbook" > problem that comes up every so often on the lists; it's quite real, > and is happening more and more often now :-/. Working on it (I've just pinged admins@freebsd.org about this). N --=20 FreeBSD: The Power to Serve http://www.freebsd.org/ FreeBSD Documentation Project http://www.freebsd.org/docproj/ --- 15B8 3FFC DDB4 34B0 AA5F 94B7 93A8 0764 2C37 E375 --- --reI/iBAAp9kzkmX4 Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.6 (FreeBSD) Comment: For info see http://www.gnupg.org iEYEARECAAYFAjtK+9EACgkQk6gHZCw343XliQCcC5sBzm9vOIaI9wOryUYl47rK 1YgAnRbvdHCHFBR0mFrLXbSkrdO7lP9K =qZs/ -----END PGP SIGNATURE----- --reI/iBAAp9kzkmX4-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20010710135753.G16152>