docs in a wiki [was Re: making review/bug filing optional

[Benton, Kevin]

> > To keep pushing the boundaries, though- why do we use docbook? It's
> > great for structured text. Do we actually use that (or, do we use it
> > more than what the HTML markup would give us?) Does it give us
> > translation benefits? Offhand, I can  see an argument to be made
that
> > the flexibility and more collaborative nature of wiki would justify
> > dumping docbook.
> 
> We use docbook because it lets us produce readable documentation in
> multiple formats.  On the website, besides the HTML version, we also
> have plaintext and a PDF.  And the PDF version is surprisingly
popular.

Interestingly enough, I've been working with CSS2 quite a bit lately and
I *REALLY* like how it supports pagination through style sheets.  One of
the biggest complaints I've had with straight HTML (no CSS pagination)
is the sense of where a page break belongs.  If we can update our CSS to
include page breaks (page-break-after, page-break-before, orphans,
widows), I think a lot of that need will be minimized.  Of course, it
assumes that users have a CSS2 compatible browser.

I've been book-writing most of my stuff lately using XHTML/CSS.  I've
put in a feature request for CSS3 Paged Media (since it's now at the
recommendation / endorsement stage) to the Firefox team so I can define
the entire printed page.  For text-based media, lynx can produce the
necessary output.

I don't know if it's really time to say we should move to XHTML/CSS for
our documentation, but it certainly is worth considering now that we can
control page breaks in a way that makes sense.

BTW - here's a portion of my "book" stylesheet for XHTML:

body {
  background-color: #FFFFFF;
}
div.author {
  font-size: medium;
  text-align: center;
  color: #999999;
  font-weight: bold;
  margin-bottom: 200pt;
}
div.byauthor {
  font-size: medium;
  text-align: center;
  color: #999999;
}
div.chapter {
  font-size: x-large;
  font-weight: bold;
  text-align: justify;
  page-break-before: always;
}
div.chaptertitle {
  font-size: x-large;
  font-weight: bold;
  text-align: center;
  padding: 24pt;
  border-top: 1pt solid;
  border-bottom: 1pt solid;
}
div.copyright {
  font-size: small;
  text-align: center;
  color: #999999;
  margin-bottom: 36pt;
}
div.section {
  font-size: large;
  font-weight: bold;
  text-align: left;
  margin-top: 10pt;
}
div.subsection {
  font-size: medium;
  font-weight: bold;
  text-align: left;
}
div.subtitle {
  font-size: x-large;
  text-align: center;
  font-weight: bold;
  margin-bottom: 216pt;
}
div.title {
  font-size: xx-large;
  text-align: center;
  font-weight: bold;
  margin-top: 144pt;
}
p, ul, li {
  font-size: medium;
  font-weight: normal;
  text-align: justify;
  page-break-inside: avoid;
  orphans: 4;
}
table {
  font-size: medium;
  font-weight: normal;
  text-align: justify;
  page-break-inside: avoid;
  orphans: 8;
}

---
Kevin Benton
Perl/Bugzilla Developer
Advanced Micro Devices
 
The opinions stated in this communication do not necessarily reflect the
view of Advanced Micro Devices and have not been reviewed by management.
This communication may contain sensitive and/or confidential and/or
proprietary information.  Distribution of such information is strictly
prohibited without prior consent of Advanced Micro Devices.  This
communication is for the intended recipient(s) only.  If you have
received this communication in error, please notify the sender, then
destroy any remaining copies of this communication.