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

Re^2: document registration policy needing to be written

Am 11.04.98 schrieb schwarz # monet.m.isar.de ...

Moin Christian!

CS> There is a major difference between dhelp and doc-base in the `development
CS> philosphy': dhelp is a `one man project'. The initial version has been
CS> designed and implemented by Marco without input of other developers
CS> (AFAIK, at least, not publicly) since he saw a need for something `better

That#s right for version 0.1.x. But I#ve ask you and Jim several times to  
work with me on *one* system. And I can#t understand why a lot of  
maintainers have got such problems to support dhelp and dwww for the hamm  
release :(.

Both system would be a good solution for hamm. And it#s not a big job to  
support this systems (work of some minutes).

And I don#t understand why you haven#t added dhelp and dwww as a  
*suggestion* to the policy for hamm.

CS> This style works fine with `standalone' programs, but doesn't work for
CS> programs which need to cooperate with a lot of other packages--like in the

Why? Should I work on the gcc compiler, if I use it?

CS> order to get it supported (by at least, a majority of packages), this
CS> would require an official policy statement. However, such a statement

That#s right, but is this a problem?

CS> would need the approval of all developers--something which is very
CS> unlikely to happen since people didn't had a possibility to talk about the
CS> design of dhelp first.

? That#s wrong. I#ve asked several times for suggestions. If the people  
don#t send comments, I can#t improve the system. And it#s no problem for  
me, to change for example the format of .dhelp or rename the file to some  
other name.

CS> (For example, I would have voted against the
CS> SGML-like registry files.)

Ok, maybe the SGML-like file is not the best idea, but I don#t like the  
format of the description field in control. I#ve suggested several times  
to develop one file for dhelp, dwww & co. But I#ve never get an answer.

CS> In contrast, I've chosen a much harder way for doc-base: There was a huge
CS> discussion about `Documentation Policy' on debian-devel (starting in June
CS> 1997), where I was desperately seeking for a compromise between the
CS> different parties about how to design a new doc policy. After a few weeks

Was this the discussion about .html.gz files? Only very few developers  
took part on this discussion. I don#t think, that we need such a  
discussion. It#s better, if some people develop the standart. After that  
all maintainers could vote. And really all maintainers and not one person  
(see the teribble Debian logo).

CS> isn't even close to be ready!) dhelp's style also has its advantages. But
CS> in order to get doc-base supported by policy, the long way is necessary.

I don#t think so and I don#t see any differences in the styles.

CS> (Again, let me stress that I don't say/think that dhelp's procedure isn't
CS> good! But we can't follow this procedure with doc-base.)

Once again, I#ve never said, that we shouldn#t change parts of dhelp. In  
fact dhelp was only one idea at the beginning. But in the current version  
dhelp is a well working system and I don#t understand, why we need doc- 
base for the HTML files.

Instead we should develop *one* .dhelp/.dwww-index/doc-base file and one  
<directory> structure. If this is done, I#ll change dhelp to support this  

CS> Comments are appreciated!

We should discuss with all maintainers, if the maintainers should ship the  
converted documents or if the users has to convert them. As owner of an  
old notebook (486SL) I don#t like the second solution and I don#t see any  

For example we could auto convert the SGML,TEXI files on master. A lot of  
people don#t have the space, to install all sgml tools to print a single  

CS> threads. (IIRC, it was the largest discussion I ever tried to "manage" as
CS> policy manager--that's why I'm so carefully about not raising the same
CS> discussion again ;-)

There was a discuss, but there was no vote and this is the problem of  
Debian in a lot of cases.

CS> Yes, these paths look ok.

No, this will not work.

CS> Note, that with the old /usr/doc/<pkg>/.dhelp files it was necessary to
CS> register all different docs (doc-ids) in a single .dhelp file. If dhelp
CS> can parse other file names than .dhelp, it's possible to have a ".dhelp"
CS> file for each doc--not only package.

That#s slow. Please keep speed in mind. Where#s the advantage of several  
small files?

CS> scripts to parse dpkg control files (e.g., Lintian), and I don't see _any_
CS> advantages from the move to SGML--only disadvantages. (But of course, feel
CS> free to start the discussion if you want.)

Ok, I agree that we could rename


to something like


But once again, that syntax of description in control is very bad. I#ve  
got troubles with the control format in some of my packages. This was the  
reason for my pseudo-SGML.

CS> No, nsgmls is no option.

I agree 100%.

CS> Remember, that doc-base will run on every system

And remember that it is called by a lot of packages. That#s the reason,  
why a Perl script in no option, too.

CS> How often would these features be needed? Languages are the only thing

I don#t like the idea. The format should be very easy.

CS> that will become important (AFAICS now), but this could easily be done
CS> with the Dpkg-style too.


  Lang: de

That#s it.

CS> far. I've written a general purpose parser of dpkg-style control files in
CS> Perl--if you want, you could update this part in the doc-base source.

No Perl, please!

CS>  .

This should be <p>.

CS>  case, ldd just reports `statically linked'.)
CS>  .
CS>  To fix this, you should explicitly specify the libraries which are
CS>  used (e.g., `-lc') when building the shared library with `ld'.
CS>  .
CS>  If you have questions about this, please contact &debdev;.

But is it possible to have something like that:

  Filename: foo1.html
  Linkname: foo1 document
  Directory: HOWTO
  Description: Line 1
    Line 2
    Line 3

  Filename: foo2.html
  Linkname: foo2 document
  Directory: HOWTO
  Lang: de
  Description: Line 1
    Line 2
    Line 3

? Must there blanks between the beginning and Line2/3? I thing, you can  
read my pseudo-SGML easier than this one, if the file is produced by a  
converter like sgml2dhelp.pl.

But if all others like this format, I could use it, that is not the  

CS>   - doesn't need additional software other than perl-base (included in
CS>     the base system)

I will *not* support this format, if I need perl. It#s no problem to write  
a parser in C, in fact all programs can use the same code for the parser.

cu, Marco

Uni: Budde@tu-harburg.de           Fido: 2:240/5202.15
Mailbox: mbudde@hqsys.antar.com    http://www.tu-harburg.de/~semb2204/

To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org

Reply to: