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

List:       kde-kdoc
Subject:    Re: Problem mixing h and idl files
From:       Sirtaj Singh Kang <ssk () physics ! unimelb ! EDU ! AU>
Date:       2000-03-06 13:17:04
[Download RAW message or body]

On Mon, Mar 06, 2000 at 11:59:06AM +0100, Wolfgang Bangerth wrote:
[snip] 
> Yes, we do, and I believe we should so. The reason is that we develop a
> library which we want others to use, so they should be able to read the
> docs easily, otherwise they won't do it at all. It might be another thing
> for authors of self-contained programs who write docs mostly for their own
> reminder.

I agree completely, but my point was that the docs should be easy to write
in the first place with errors causing minimal damage. This is certainly
not the case with using any SGML tags (where there might be spelling errors
or unclosed tags etc).


[snip] 
> I guess, substituting SGML for alll the other printed formats is a good
> thing in principle. However, I'm not so happy to have to force all those
> who want to use it (and Jade) to modify their TeX startup files for bigger
> sizes. Has anyone tried to figure out why Jade fails to produce reasonable
> TeX output from kdoc-generated SGML? Is this a problem of the SGML output,
> or of the conversion by Jade?

I honestly can't tell, the only reference I found to the problem was in
one page I found using google.com. I agree that it is too much to ask
people to edit their TeX configuration, especially given that many people
using shared machines may not have the privilege to do so. Of course I
think this problem may be alleviated eventually as more people begin to
use DocBook and jade for larger documents.

> In my eyes, the HTML output is superb and does not need much refinement.
> However, for the fun-factor...

I can never discount the fun factor, the important thing being that it
doesn't get in the way of the "serious" users. :) CSS is a good way to
do this.

> 
> But, back to tags: I had a weekend to think things over, and I am now no
> more convinced that embedding SGML and translating it into HTML is a good
> idea. The problem is that these tags with their many <>'s and nonlocality
> (<x>...</x>) are so particularly hard to parse. What would probably be
> simpler are indeed @x{...} tags.

@x{} is a good one. So hyperlinks may become @www{link, text} etc.

> If we could reach agreement about what tags should be supported, I guess
> that we would consider implementing them for HTML and SGML. I myself would
> suggest @p{...}, @em{...}, @sect[1-4]{...}, and some that I have forgotten

Nitpick: @sect is a section heading, therefore should have the same
semantics as @param etc (as it currently does).

> hard once we know what we want. The `deref' functions should be the right
> place, I guess. Is it possible to come to such an agreement?
 
Sure, I agree in principle, but I cannot do the work for a little while as
I have just started a new contract two weeks ago. I'm still looking for
a way to work on kdoc on company time. :) There is the chance that
kdoc will support java too as I am currently using that.

There are still some major features that I have to complete first anyway.
The class/function grouping system and proper linking of namespaces is
definitely of higher priority, as is the completion of the KDOC users'
guide.

-Taj.

Quiz: how many of you have discovered the --html-logo feature? :)

Sirtaj S. Kang       taj@kde.org         ssk@physics.unimelb.edu.au
Univ of Melbourne	The "gui" in "Penguin" is pronounced "K-D-E"

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