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

Roland Illig <rillig@NetBSD.org> wrote:
> Jan Schaumann wrote:

> >I'd like to start a detailed discussion about how we can make this
> >happen.  I think we should first figure out what exactly our goals are
> >in the documentation management framework.  Here's what I came up with:
> >
> >- we want to have a consistent layout, look and feel for all pages
>=20
> - including some links for easy navigation -- preferably in the header=20
> of each page.

Hmmm.  If you refer to something like we currently have (<link rel>),
then I'm not sure I find that very useful for a regular website (in
contrast to a consistent and self-contained section like the Guide).  A
normal website doesn't really have a hierarchical structure, I think.

But maybe I misunderstood, and you ment having a common set of links in
the header or footer that go to, say

'Home Page'  'Search'  'Documentation' 'About'

like FreeBSD has now?

That ought to be fairly easy via either stylesheets, inclusion or
automatically generated header/footer for all pages.

> - Some macro or &entity; to refer to other pages reliably, even if
>   the physical location moves. &htdocsdir; comes to mind -- in analogy
>   to ${PKGSRCDIR}.

I think this could also be a low priority.  We don't move content around
enough to want to be able to refer to one page and easily relocate it.

> - User-defined and system-defined macros, especially if we stay with
>   XML/DocBook. It's a nuisance to type=20
> <varlistentry><term><varname>FOO</varname></term><listitem><para>Descript=
ion</para></listitem></varlistentry>=20
> for sixteen times.

We currently do have this capability.  For example &man.foo.N; via
htdocs/share/xml/man-refs.ent.

> - Whether we stay with DocBook or not, there shall be documentation for=
=20
> end users on how to write web pages

Yes!

-Jan

--=20
"Life," said Marvin, "don't talk to me about life."

--X1bOJ3K7DJ5YkBrT
Content-Type: application/pgp-signature
Content-Disposition: inline

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (NetBSD)

iD8DBQFD3SxifFtkr68iakwRAh72AJ4v+N6yaNmoeIrodgaMdVUo6iyE3wCgltrR
XT9GOFctWROEq0pZTw0M4Ck=
=mKyb
-----END PGP SIGNATURE-----

--X1bOJ3K7DJ5YkBrT--