Re: DOCBOOK: A straw proposal for help topics in DocBook

[Nik Clayton <nik@freebsd.org>]

--gvF4niNJ+uBMJnEh
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

Catching up on my e-mail.

On Tue, Oct 16, 2001 at 01:56:25PM -0400, Norman Walsh wrote:
> There's been a fair amount of discussion about how to make DocBook
> more help-friendly. Since we don't seem to be making a lot of progress
> in the absence of a concrete proposal, attached is my first draft of a
> concrete proposal. There, now there's something to throw rocks at. :-)
>=20
> Why are we doing this:
>=20
> 1. Because help documentation is less book-like and more topic-oriented
>    than DocBook appears to be.
> 2. Because there are other motivations for a "topic" wrapper even within
>    book-oriented documentation.
> 3. As a side benefit, I think this proposal makes it possible to write
>    task-oriented documentation (e.g., in the DITA architecture) independe=
nt
>    of the specific help context. (This is just speculation, I haven't
>    done any study on this point.)

Didn't Mike Smith come up with a nifty way of remapping DocBook elements
to other element names?

IIRC, the rationale was that DocBook's sufficiently flexible that it can
accommodate many different structures.  But people feel more comfortable
writing:

    <help>
      <topic> ... </>
      <topic> ... </>
      <topic> ... </>
    </help>

(or whatever) than they do using

    <article>
      <section> ... </>
      <section> ... </>
      <section> ... </>
    </article>

Why not use that approach, instead of adding new elements to DocBook?

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

--gvF4niNJ+uBMJnEh
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

iEYEARECAAYFAjvf2UEACgkQk6gHZCw343UTSwCeMJyqPY9SL/Rc2HBy4VjgwMWG
fboAoJOu5I3eTy8K1fvNZbrk7Wd4RLr5
=x/ok
-----END PGP SIGNATURE-----

--gvF4niNJ+uBMJnEh--