Previous mail
Next mail
Unformatted/full headers
Overview 10 days
Subject
Date
Thread
Author
From: Richard D. Jackson
Subject: Some observations [GHJ]
Date: 1 Feb 2003, 20:27:58
On Fri, 2003-01-31 at 23:06, Frank Heckenbach wrote:
> <snip>
> > Take a look at this
> > http://java.sun.com/j2se/1.4.1/docs/api/index.html
> > ignore the stuf at the top and scroll down to the section containing the
> > method documentation. This is the type of format/output I would like to
> > see the html ouput engine produce for a function/procedure. I wouldn't
> > mind seeing that type of output on the texinfo side either but I
> > definatly want it on the html side. Now to do that type of formating
> > will require that the documenter mark what is what.
>
> Could you please give an exact URL of the page you mean? The URL
> above contains a frameset with several menus, I'm not sure exactly
> what to look at.
>
Sorry about that try this:
http://java.sun.com/j2se/1.4.1/docs/api/java/awt/Paint.html
And look at the Method Detail section at the bottom. There happens to be
only one method for this but it does show what I'm thinking about.
> > > > referance
> > >
> > > Yes, quite important. As I wrote in my program's comments, I'd
> > > prefer to make them as easily as possible, e.g., <foo> will write
> > > the identifier foo in the text, but also put it in the references
> > > section. It might seem a small issue, but not having to write the
> > > thing twice (in the text and the references) is more comfortable and
> > > will probably encourage people to use many references. :-)
> > The problem with using <foo> would be that now to include a <> in your
> > documentaion would mean you have to escape it so that a ref is not
> > created. So I think the first thing to deside is what do you use to
> > denote a command. example @ % * ~ whatever it is I would prefer
> > something that will mostlikly not be needed in the docmentation so we
> > don't have to worry about escapes.
>
> But code samples which can include `<>', `@' etc. should already be
> marked up as such. That's why I suggested `...' for code samples in
> my draft. Markup within code samples is pointless and shouldn't be
> recognized, therefore these characters are "harmless".
>
> OK, I admit, the single quote (') can appear in Pascal, so using it
> for the end of a code block is not good. So I'd now prefer another
> delimiter such as one of the chars that doesn't occur in any Pascal
> dialect which seem to be !%`|~, so perhaps |code| or `code` (hmm?)
> ...
>
Ok I get it this time :)
> > > I basically agree. Though I think there is some amount of markup we
> > > need. E.g., to mark identifiers (see above, with references for
> > > identifiers mentioned besides the current ones), and to mark
> > > sections of code etc. E.g., the description of gpc.pas:CanRead
> > > currently says:
> > > [...] This is similar to `not EOF (aFile)', but [...]
> > >
> > > So the `not EOF (aFile)' part should be marked in some way to avoid
> > > confusion -- preferably (to me) `...' in the input and @samp{...} in
> > > the texi output.
> > >
> > Yes I do agree with you in that we should have things like bold and
> > italics
>
> Nitpick: I don't want stuff like bold and italics, but stuff like
> emphasis and "code" markup (i.e., no physical, but logical markup).
>
Ok
> > > Also, it *might* be useful to write emphasis sometimes. In plain
> > > text formats which don't provide for this, people will often use
> > > *...* for it, so a tool could just as well convert it to proper
> > > emphasis in the output.
> > Yes the documenter can indicate that he/she wants emphasis and leave it
> > up to the backend to decide how to do it.
>
> Exactly.
>
> > > > First the question I would have is what is the target application of the
> > > > documenter? If for only documenting single monolithic units then a
> > > > single pass ( single file ) tool would do the job. But on the other hand
> > > > if you want to handle multi-module/unit applications that need to beable
> > > > to cross link the documention and or have a unified cross-referance
> > > > amogst all the code modules then what you really want to do is process
> > > > all of the files in a single pass.
> > >
> > > Not necessarily. If you're worried about cross-references, Texinfo
> > > handles them already (see below).
> > >
> > Yes Texinfo does but HTML does not. True you can just output Texinfo and
> > then convert that to HTML but doing it that way you loose some of the
> > things you can do in HTML that Texinfo was not designed for.
>
> I don't think we should use any such things in the documentation at
> all, i.e. stick to the lowest common denominator. Or do you have
> anything in particular in mind which is absolutely essential and not
> possible to texi?
>
> I also don't think it's worth the extra effort to create HTML
> directly rather than going via texi. At least for the GPC website, I
> probably wouldn't use it, anyway, since it's generated from one texi
> source so references work best.
>
Maybe I need to spend some time and learn texinfo better. As right now I
know very little about what it can and can't do.
> > > It's different when you want to refer to things from other projects
> > > (e.g., you write documentation for your own code and want to refer
> > > to the GPC manual directly). BTW, that's no different whether the
> > > tool will translate single or multiple files, since different
> > > projects are translated separately, anyway. Actually, all that's
> > > required then is to get the name of the other documentation file --
> > > the texi reference would then look like `@ref{WriteLn,,,gpc}'
> > > instead of `@ref{WriteLn}'.
> > >
> > Again how would you go directly to WriteLn in the texi file. Yes going
> > to the main menu of the texi file would be easy but I want to link
> > directly into it.
>
> Well, just what I wrote. `@ref{WriteLn,,,gpc}' goes to the node
> `WriteLn' in the file `gpc' (in info and also the other texi
> outputs).
>
> > > To do this automatically, the cross reference list you suggested
> > > might be useful. I.e., while translating the GPC documentation, this
> > > list is produced and stored somewhere, and when translating the
> > > documentation of another project, it could use this list to find out
> > > which identifiers should have their references pointing to the GPC
> > > documentation.
> > >
> > Exactly! And with the list would be the exact link to it so you can go
> > directly to it. The problem is that Texinfo will split it up and I don't
> > know enough texinfo yet to look into how to do that for texinfo. HTML
> > would be easy as you are going direct to finished output where as
> > texinfo files will still need to be processed by maketexi?
>
> (makeinfo)
>
> But I think you're thinking of texi references as more difficult
> than they are -- unless I'm missing something ...
>
> > > Grant Jacobs wrote:
> > > > Don't include format per se, but include some style class information
> > > > like 'header' 'text' etc so that it can be appropriately formatted
> > > > later.
> > >
> > > I'd prefer sections to headers. The difference may be small, but
> > > rather than inserting headers here and there, this will structure
> > > the documentation. I suppose that smaller units will not need
> > > sections at all, but for larger ones they could be useful. One
> > > hierarchy level should be enough, though.
> > >
> > Yes and even better do the section at the top and down in the
> > function/procedure documenation have a tag that indicates what section
> > this belongs to. That way you have the formater do the work of filling
> > out the section documentation.
>
> I don't know exactly how you mean this, but what I do not want is to
> have to specify the section for each declaration. Most of the time,
> declarations belonging in one section are written next to each other
> (and I don't even see a problem to make this a fixed rule), so
> specifying where a new section starts should be all that's required.
>
> > But I do think the first things we need to decide is what do we use to
> > indicate a command/tag and what tags/commands do we need. And what the
> > tag/command should do. Lets keep it to that for now and leave how it
> > should work or how you should use them for later. For example:
> >
> > ~ = this indicates a command ( I'm not advicating ~ it is just a good
> > starting point as it is not reserved, it is not a compiler commad like
> > {@ is and will most likly not be used in documentation. )
>
> See above.
>
> > ~bold = this will mark the following text in bold.
> > ~end = This ends a format command.
>
> My problem with these are that they make the text (in the source
> form) harder to read -- it's easier (mentally) to read over symbols
> than words.
>
> That's why I suggested symbolic forms for the most common purposes
> (`...', <...>, *...*). And even for the occasional "named" command,
> I prefer a symbol at the end (such as @foo{...}).
>
As I stated above I need to learn more about texinfo. And I do agree
that symbolic forms are/should be easer to read. Anyways give me a
little time to look into texinfo a little more for the output side. But
in the mean time I think we need to move this discusion over to what
symbols do we need, What can we figure out from the code so don't need
symbols for ect....
I will try to make a first pass today if for no other reason than to get
it going.
Richard
Previous mail
Next mail
Unformatted/full headers
Overview 10 days
Subject
Date
Thread
Author
Note: This page contains information that does not originate from the owner of this web site, but from the authors of the mails archived. The owner of this web site is not responsible for the content of such information. Any use of that infomation requires the consent of the respective author.
Where WWW addresses (URLs) in the mails archived are marked as hyperlinks, this is only for the comfort of the reader. The content of the web pages linked to like this does not necessarily reflect the opinion of the owner of this web site or of the authors of the mails archived. The owner of this web site is not responsible for the content of such web pages. Those pages are explicitly not to be considered as part of the content of this page, but merely as references.
This page was created by Crystal 0.999 (Linux 2.4.27/i686).