Menu
▾
▴
naviserver-devel
|
From: Zoran V. <zv...@ar...> - 2005-07-27 17:33:02
|
Hi,
Before I spend more time, just want to give you some
idea about it. Please download those:
http://www.archiware.com/www/downloads/Ns_ConnHeaders.man
http://www.archiware.com/www/downloads/Ns_ConnHeaders.3
http://www.archiware.com/www/downloads/man.macros
and use:
nroff -man Ns_ConnHeaders.3 | more
to look at it.
The ".man" is the source file I used. Out of this file
we can make wiki, html, nroff etc pp formats with doctools.
I have patched the doctools to include new formatting
command "ccall" which stands for "C-call" and is a
companion to "call" which formats Tcl ccommands.
I did the nroff formatter first. Once we settle on this
one, I will update the rest of formatters, eventually
producting a private version of doctools for our needs.
We can post changes to tcllib folks so they can include
this in the standard distro if they like.
While doing those changes, I now have much better insight
how doctools are working and I can produce now just about
any layout you'd like.
Lets hear your feedback.
Zoran
|
|
From: Vlad S. <vl...@cr...> - 2005-07-27 18:08:11
|
Looks interesting. So all the docs will need to be re-written in doctools format. Zoran Vasiljevic wrote: > Hi, > > Before I spend more time, just want to give you some > idea about it. Please download those: > > http://www.archiware.com/www/downloads/Ns_ConnHeaders.man > http://www.archiware.com/www/downloads/Ns_ConnHeaders.3 > http://www.archiware.com/www/downloads/man.macros > > and use: > > nroff -man Ns_ConnHeaders.3 | more > > to look at it. > > The ".man" is the source file I used. Out of this file > we can make wiki, html, nroff etc pp formats with doctools. > > I have patched the doctools to include new formatting > command "ccall" which stands for "C-call" and is a > companion to "call" which formats Tcl ccommands. > > I did the nroff formatter first. Once we settle on this > one, I will update the rest of formatters, eventually > producting a private version of doctools for our needs. > We can post changes to tcllib folks so they can include > this in the standard distro if they like. > > While doing those changes, I now have much better insight > how doctools are working and I can produce now just about > any layout you'd like. > > Lets hear your feedback. > > Zoran > > > > > ------------------------------------------------------- > SF.Net email is sponsored by: Discover Easy Linux Migration Strategies > from IBM. Find simple to follow Roadmaps, straightforward articles, > informative Webcasts and more! Get everything you need to get up to > speed, fast. http://ads.osdn.com/?ad_id=7477&alloc_id=16492&op=click > _______________________________________________ > naviserver-devel mailing list > nav...@li... > https://lists.sourceforge.net/lists/listinfo/naviserver-devel -- Vlad Seryakov 571 262-8608 office vl...@cr... http://www.crystalballinc.com/vlad/ |
|
From: Zoran V. <zv...@ar...> - 2005-07-27 18:14:50
|
Am 27.07.2005 um 20:08 schrieb Vlad Seryakov: > Looks interesting. So all the docs will need to be re-written in > doctools format. > Well, there is not much available out-there. But, giving it a doctool looks we can concentrate on content and make nroff/html/wiki automatically by a "make htmldoc" or "make mandoc" or whatever... zoran |
|
From: Bernd E. <eid...@we...> - 2005-07-28 05:16:35
|
Hi Zoran, the doctools source looks good, should be manageable! > http://www.archiware.com/www/downloads/Ns_ConnHeaders.man > http://www.archiware.com/www/downloads/Ns_ConnHeaders.3 This one seems not to be on your server: > http://www.archiware.com/www/downloads/man.macros > > and use: > > nroff -man Ns_ConnHeaders.3 | more Returns empty and Midnight Commander (mc) says "Empty output from child filter". What do I do wrong? Bernd. |
|
From: Zoran V. <zv...@ar...> - 2005-07-28 07:55:18
|
Am 28.07.2005 um 07:18 schrieb Bernd Eidenschink: > > Hi Zoran, > > the doctools source looks good, should be manageable! Yes. This is fairly simple. > > >> http://www.archiware.com/www/downloads/Ns_ConnHeaders.man >> http://www.archiware.com/www/downloads/Ns_ConnHeaders.3 >> > > This one seems not to be on your server: > >> http://www.archiware.com/www/downloads/man.macros Ups? It is now, sorry... >> >> and use: >> >> nroff -man Ns_ConnHeaders.3 | more >> > > Returns empty and Midnight Commander (mc) says "Empty output from > child > filter". What do I do wrong? > I don't know. Alternatively, you can copy the Ns_ConnHeaders.3 into /usr/local/man/man3 and just say "man Ns_ConnHeaders"... Zoran |
|
From: Stephen D. <sd...@gm...> - 2005-07-30 01:58:06
|
On 7/27/05, Zoran Vasiljevic <zv...@ar...> wrote: > Hi, >=20 > Before I spend more time, just want to give you some > idea about it. Please download those: >=20 > http://www.archiware.com/www/downloads/Ns_ConnHeaders.man The following two have the same contents: > http://www.archiware.com/www/downloads/Ns_ConnHeaders.3 > http://www.archiware.com/www/downloads/man.macros >=20 > and use: >=20 > nroff -man Ns_ConnHeaders.3 | more >=20 > to look at it. >=20 > The ".man" is the source file I used. Out of this file > we can make wiki, html, nroff etc pp formats with doctools. >=20 > I have patched the doctools to include new formatting > command "ccall" which stands for "C-call" and is a > companion to "call" which formats Tcl ccommands. >=20 > I did the nroff formatter first. Once we settle on this > one, I will update the rest of formatters, eventually > producting a private version of doctools for our needs. > We can post changes to tcllib folks so they can include > this in the standard distro if they like. >=20 > While doing those changes, I now have much better insight > how doctools are working and I can produce now just about > any layout you'd like. >=20 > Lets hear your feedback. >=20 > Zoran [ccall [type int] Ns_ConnLocationAppend [type Ns_Conn] [arg *connPtr] [type Ns_DString] [arg dest]] A C-call always has a name, always returns something (even if it's just void), all args are typed and named, etc., and a lot of that can be inferred from position and so on. But in the above, the doc writer must redundantly specify [type Ns_Conn] [arg *connPtr]. Couldn't the macro ccall just handle a lot of this transparently?=20 Something like: [ccall int Ns_ConnLocationAppend { {Ns_Conn *connPtr} {Ns_DString *dest} } { Describe me here... }] |
|
From: Zoran V. <zv...@ar...> - 2005-07-30 07:42:45
|
Am 30.07.2005 um 03:58 schrieb Stephen Deasey:
>
> [ccall [type int] Ns_ConnLocationAppend [type Ns_Conn] [arg *connPtr]
> [type Ns_DString] [arg dest]]
>
> A C-call always has a name, always returns something (even if it's
> just void), all args are typed and named, etc., and a lot of that can
> be inferred from position and so on. But in the above, the doc
> writer must redundantly specify [type Ns_Conn] [arg *connPtr].
>
> Couldn't the macro ccall just handle a lot of this transparently?
> Something like:
>
> [ccall int Ns_ConnLocationAppend {
> {Ns_Conn *connPtr}
> {Ns_DString *dest}
> } {
> Describe me here...
> }]
>
Of course it could. This is how I did it in the first place.
But, I'm still not sure and will have to investigate this,
but it appears to me that other parts of the engine (TOC and Index
generators) can take advantage of those [type] declarations.
If this is not true, then there is absolutely no reason why
not to code like that. I made the [ccall=10] resemble the [call]
but there is no reason why one could/should not make it like:
ccall int Ns_ConnLocationAppend {{Ns_Conn *connPtr} {Ns_DString =20
*dest}}
I will put this into and give another round.
Zoran
=20=
|
|
From: Stephen D. <sd...@gm...> - 2005-07-30 09:50:50
|
On 7/30/05, Zoran Vasiljevic <zv...@ar...> wrote:
>=20
> Am 30.07.2005 um 03:58 schrieb Stephen Deasey:
>=20
> >
> > [ccall [type int] Ns_ConnLocationAppend [type Ns_Conn] [arg *connPtr]
> > [type Ns_DString] [arg dest]]
> >
> > A C-call always has a name, always returns something (even if it's
> > just void), all args are typed and named, etc., and a lot of that can
> > be inferred from position and so on. But in the above, the doc
> > writer must redundantly specify [type Ns_Conn] [arg *connPtr].
> >
> > Couldn't the macro ccall just handle a lot of this transparently?
> > Something like:
> >
> > [ccall int Ns_ConnLocationAppend {
> > {Ns_Conn *connPtr}
> > {Ns_DString *dest}
> > } {
> > Describe me here...
> > }]
> >
>=20
> Of course it could. This is how I did it in the first place.
> But, I'm still not sure and will have to investigate this,
> but it appears to me that other parts of the engine (TOC and Index
> generators) can take advantage of those [type] declarations.
> If this is not true, then there is absolutely no reason why
> not to code like that. I made the [ccall=10] resemble the [call]
> but there is no reason why one could/should not make it like:
>=20
> ccall int Ns_ConnLocationAppend {{Ns_Conn *connPtr} {Ns_DString
> *dest}}
>=20
> I will put this into and give another round.
Great. Are the macros expanded recursively? Can ccal output the type
declarations for the benefit of indexes etc.? Will we be able to
document the Tcl cmds as easily?
Oh, and can the index be categorized (used to live here:
http://aolserver.com/40drafts/ do you remember?) rather than just fill
the screen, as the Tcl API docs do:
http://www.tcl.tk/man/tcl8.4/TclLib/contents.htm ?
Also, is it possible to do things like mark a function deprecated, and
when, so that is doesn't show up in the normal doc index but an index
of deprecated functions is created, grouped by version number.
How do we specify CONST, and can we document args as in, out or inout?
How about NONNULL args, varargs and format strings?
I'm just wondering how flexible this thing is. My mental model is
that it just calls [subst] on the man page source, so things like
literal text would seem hard to hide or move around...
|
|
From: Zoran V. <zv...@ar...> - 2005-07-30 10:04:34
|
Am 30.07.2005 um 11:50 schrieb Stephen Deasey: > > Great. Are the macros expanded recursively? Can ccal output the type > declarations for the benefit of indexes etc.? Will we be able to > document the Tcl cmds as easily? I will first have to examine the TOC and index parts before I can say something about that. Tcl commands are already handled by doctools with ease (doctools was designed arround documenting Tcl commands primarily). > > Oh, and can the index be categorized (used to live here: > http://aolserver.com/40drafts/ do you remember?) rather than just fill > the screen, as the Tcl API docs do: > http://www.tcl.tk/man/tcl8.4/TclLib/contents.htm ? Good question. Again, the TOC/Index parts I have not scratched yet. But I assume we can make just about anything once we understand the guts of it. I've made efforts to understand the formatting engine first to be able to get an idea how we could expand it to document C-calls nicely. Once this is done (and I believe we're very close to it), I will take the rest under examination. > > Also, is it possible to do things like mark a function deprecated, and > when, so that is doesn't show up in the normal doc index but an index > of deprecated functions is created, grouped by version number. > > How do we specify CONST, and can we document args as in, out or inout? > How about NONNULL args, varargs and format strings? Uhuhuhuhu... args in/out is already handled. You can group args definitions more/less like Tcl is doing it in their docs (look "man Tcl_SetObjResult" for example). For the other, dunno. We'll have to see... > > I'm just wondering how flexible this thing is. My mental model is > that it just calls [subst] on the man page source, so things like > literal text would seem hard to hide or move around... > It is pretty flexible, once you understand how it works. As it is all in plain Tcl and in just couple of relatively short files, you can pretty quickly get an idea how to change it, when needed. What I want to minimize is the scope of changes and use the thing more/less as-is in order to put a lower acceptance barrier on the doctools maintainer(s). If we manage to get at least "ccall" in and supprted *by them* it will be a great thing. Zoran |
|
From: Stephen D. <sd...@gm...> - 2005-07-30 10:35:36
|
On 7/30/05, Zoran Vasiljevic <zv...@ar...> wrote:
>=20
> Am 30.07.2005 um 11:50 schrieb Stephen Deasey:
> >
> > Great. Are the macros expanded recursively? Can ccal output the type
> > declarations for the benefit of indexes etc.? Will we be able to
> > document the Tcl cmds as easily?
>=20
> I will first have to examine the TOC and index parts before I can
> say something about that.
>=20
> Tcl commands are already handled by doctools with ease (doctools
> was designed arround documenting Tcl commands primarily).
Yeah, I was looking at your thread docs:
[call [cmd thread::create] [opt -joinable] [opt -preserved] [opt script]]
Same deal as with the ccall, all the [opt] stuff seems redundant. For
documenting Tcl cmds, it would seem possible to use *exactly* the same
syntax as one would to define a proc:
call name -opt -- arg {arg2 def} args
> >
> > Oh, and can the index be categorized (used to live here:
> > http://aolserver.com/40drafts/ do you remember?) rather than just fill
> > the screen, as the Tcl API docs do:
> > http://www.tcl.tk/man/tcl8.4/TclLib/contents.htm ?
>=20
> Good question. Again, the TOC/Index parts I have not scratched
> yet. But I assume we can make just about anything once we understand
> the guts of it. I've made efforts to understand the formatting engine
> first to be able to get an idea how we could expand it to document
> C-calls nicely. Once this is done (and I believe we're very close to
> it), I will take the rest under examination.
>=20
> >
> > Also, is it possible to do things like mark a function deprecated, and
> > when, so that is doesn't show up in the normal doc index but an index
> > of deprecated functions is created, grouped by version number.
> >
> > How do we specify CONST, and can we document args as in, out or inout?
> > How about NONNULL args, varargs and format strings?
>=20
> Uhuhuhuhu... args in/out is already handled. You can group args
> definitions
> more/less like Tcl is doing it in their docs (look "man
> Tcl_SetObjResult"
> for example).
>=20
> For the other, dunno. We'll have to see...
>=20
> >
> > I'm just wondering how flexible this thing is. My mental model is
> > that it just calls [subst] on the man page source, so things like
> > literal text would seem hard to hide or move around...
> >
>=20
> It is pretty flexible, once you understand how it works. As it is
> all in plain Tcl and in just couple of relatively short files, you
> can pretty quickly get an idea how to change it, when needed.
> What I want to minimize is the scope of changes and use the thing
> more/less as-is in order to put a lower acceptance barrier on the
> doctools maintainer(s). If we manage to get at least "ccall" in
> and supprted *by them* it will be a great thing.
Agree. Would be best to get any changes accepted upstream.
Also, no need to go nuts up front, we can add things later.
I just wonder if the system is too simple. In your example man page
you followed each ccall definition with a description. In the Tcl man
pages the definitions are grouped at the top, then the args are
described, then there's some prose text describing the functions.
If the source looked like:
ccall int FooFunc {{int arg}} {
p { description... }
p { more... }
}
I could see how a tree was being built up, and how formatting
functions could walk it and output in any order, and use the data to
synthesize lists and tables etc. But with the simple macros embedded
in literal text, it looks like the formatters will be limited to the
order in which things are presented in the source man page. Or am I
way off here..?
|
|
From: Zoran V. <zv...@ar...> - 2005-07-30 10:48:03
|
Am 30.07.2005 um 12:34 schrieb Stephen Deasey:
>
> I just wonder if the system is too simple. In your example man page
> you followed each ccall definition with a description. In the Tcl man
> pages the definitions are grouped at the top, then the args are
> described, then there's some prose text describing the functions.
This kind of layout is also possible to achieve, but I deliberately
avoided it because I find it extemely difficult to follow if you
have about 20 calls decribed in one page.
We can emit arg definitions a'la Tcl-man in the SYNOPSIS section,
this is no big deal.
>
> If the source looked like:
>
> ccall int FooFunc {{int arg}} {
> p { description... }
> p { more... }
> }
>
> I could see how a tree was being built up, and how formatting
> functions could walk it and output in any order, and use the data to
> synthesize lists and tables etc. But with the simple macros embedded
> in literal text, it looks like the formatters will be limited to the
> order in which things are presented in the source man page. Or am I
> way off here..?
You are not, but getting this done this way would mean even more
chages in the way how text is parsed. The doctools maintain some
state between passes and you have to fiddle with this, which I
really wanted to avoid. I already had to make changes to this state
by introducing the ccall formatter... Less changes = better.
I believe with some tweaks on the ccall systax we can get what
we want and avoid too much modifications. I will take some of the
ideas from here and give it another round. Lets see if that'll
be more appealing.
Zoran
|
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X