[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-i18n-doc
Subject:    Re: Fwd: RFC: include SGML-/Snapshot-links in docs
From:       Frederik Fouvry <fouvry () sfs ! nphil ! uni-tuebingen ! de>
Date:       1999-11-30 16:23:26
[Download RAW message or body]


Hi, 

> I'm not completely in favour of the following ideas, for maintenance reasons,
> but they are at least worth discussing them.
> 
> (to Andreas : thanks for your contribution ! We'll see what comes out of it.)
> 
> ----------  Message réacheminé  ----------
> Subject: RFC: include SGML-/Snapshot-links in docs
> Date: Wed, 24 Nov 1999 19:52:18 +0100
> From: Andreas Schlapbach <schlpbch@bluewin.ch>
> 
> Dear Eric
> 
> As you seem to be involved in the KDE documentation (you post
> doc-related stuff to kde-devel), let me propose two modifications to the
> structure of the documents.
> 
> - Include a link to the sgml file of a document
> 
> The reason is this: First, if a document is split up in numerous
> html-files, it's a real pain printing it. If there would be a link, one
> could just download the sgml-file, convert it to PS and print it. It
> would also help reducing phone bills, because getting one sgml-files is
> easier then getting all html-files..

It wouldn't be a big problem to do that, we'd just have to take care
of including the SGML source we converted from, and *not* the most
current one.  BTW: PS is a format that will be provided at some stage
(it's one of the next things to do).  For quite a few languages, it
can be done, but you need jadetex working ...

So in short, I'm not against it, but there are the following things to
consider:
- PS will be provided together with HTML at some stage (or am I
  mistaken in this?);

- the scripts that create the distribution will be a bit more
  complicated because they need to know what file the HTML comes from,
  I'm not sure whether this information is available in the style
  sheets, in which case it gets a bit fragile.  Moreover, there will
  be a period of inconsistency when the SGML file is updated, and the
  HTML file isn't yet.

- All SGML documentation will have (or already has) a fixed place
  somewhere, so if that is advertised clearly, there is no need to
  make the link in the documentation itself.  It is fairly easy to 
  add a standard text to the documentation on where to find the source
  of the documentation - as long as it's standard.

> - Include a link to the latest snapshot of the program documented.

Important note: the documentation is not always up-to-date with the
latest version of the software, so that the programmes might have even
got a different home page!  Whereas in the previous point, I can see
the use of it, I don't think it is useful to know where the latest
snapshot is.  And it is a snapshot after all - it would be better to
take the latest release, and the documentation of different languages
should be able to point to different releases: what is the strategy to
follow: point to the latest, or point to the version of the software
of which the documentation was translated?  As Eric mentioned, there
are some maintenance problems with this.

> I know that KDE is working with CVS, but I spent hours trying to figure
> out where to get one and only program (which tar ball? which
> directory?). It would also be confinend, if there was a possibility to
> download just the files needed (say kppp) than the whole tar ball
> (kdenetworks). An automatic check out from the CVS-server would be
> handy. But there should at least be a _working_ link to the latest
> snapshot.
> 
> If this could be made standard, this would help improving the
> user-friendlyness of KDE, reduce the noise to KDE mailing lists and help
> getting new users/hackers involved. It would be in the interest of all,
> to somehow force people writing docs/programs to stick to this.
> 
> Example:
> 
> ..
> <<sect>Copyright<p>
> 
> 
> Kset Copyright 1999 Andreas Schlapbach , <htmlurl
> url="mailto:schlpbch@iamexwi.unibe.ch" name="schlpbch@iamexwi.unibe.ch">
> 
> This document can be found <htmlurl url="..." name="here">
> The newest snapshot ist available <htmlurl url".." name="here">

Well, it's not too hard to do it, but it cannot really be enforced in
SGML, which means that you cannot rely on it.  But we could ask the
documentation authors to do it (but because they're not always the
developers, again, it is not reliable).

I like the proposals as such, but for maintenance reasons, they're a
bit hard to enforce.

Frederik

[prev in list] [next in list] [prev in thread] [next in thread]