[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Why documentation and programs should not be treated alike

On Tue, Sep 23, 2003 at 07:13:13PM -0400, Richard Stallman wrote:
> In the "compiled" form of a manual, as long as there is no DRM to stop
> you from reading it, everything that matters is plain to see.  You see
> the contents, and you even see the fonts and indentation that were
> selected by the markup.  The markup commands, which you don't see, and
> any comments in the markup, are far less important than what you do
> see.  If you can read the published manual, what you see is everything
> that really matters.

That is not always true. Some of the document formats you have defined
as Transparent include conditionals, loops, and other programming
constructs. As an example, have a look at
/usr/share/doc/gs/examples/waterfal.ps ; but the same is true for
(La)TeX. With such formats, a manual could be written that would exclude
all non-relevant system-specific data based on the operating system or
kernel it was converted on -- for instance, a manual written in
LaTeX that explains installing, configuring, and running a specific
program could only include the FreeBSD-specific parts when 'compiled' on
a FreeBSD system.

In that case, you don't just lose comments and markup constructs, but
also content.

Wouter Verhelst
Debian GNU/Linux -- http://www.debian.org
Nederlandstalige Linux-documentatie -- http://nl.linux.org
"Stop breathing down my neck." "My breathing is merely a simulation."
"So is my neck, stop it anyway!"
  -- Voyager's EMH versus the Prometheus' EMH, stardate 51462.

Attachment: signature.asc
Description: Digital signature

Reply to: