You are viewing a plain text version of this content. The canonical link for it is here.
Posted to rivet-dev@tcl.apache.org by Massimo Manghi <ma...@unipr.it> on 2007/11/08 15:19:45 UTC
structured command synopsis
I'm going to work tonight on the docs and I would
like to fix the pages of the commands encapsulated
in the 'Rivet' package.
As it turned out the alternate name I had proposed
('Rivetlib') was already taken in init.tcl and
unless someone comes up with a better idea I will
keep this name.
I wonder whether DocBook has an orthodox way to have
more structured command synopsises. The goal is
simple: every command in the package 'Rivet' must
show clearly that a 'package require Rivet' has
to come in advance to the command. The tag
'synopisisfragment' can be the right way to do it?
I think I can do it by trial and error, but maybe
a DocBook expert like David has the right answer.
ciao
-- Massimo
---------------------------------------------------------------------
To unsubscribe, e-mail: rivet-dev-unsubscribe@tcl.apache.org
For additional commands, e-mail: rivet-dev-help@tcl.apache.org
Re: structured command synopsis
Posted by Massimo Manghi <ma...@unipr.it>.
On Thu, 8 Nov 2007 15:29:26 +0100, David Welton wrote
> I'm not quite sure what you mean - you just want it to print out the
> 'package require Rivet' somewhere?
>
yes. I want it to be printed before the command synopsis
with a chance to use a specific style for it.
Something like
<cmdsynopsis>
<command>package require Rivet</command>
<command>escape_shell_command</command>
<arg>string</arg>
</cmdsynopsis>
prints everything on the same line using the same
style. I would like to have an output like
package require Rivet x.x
...
escape_shell_command
marking the need to have the first line somewhere
in the code in order to have the command available
to the interpreter
> This is the definitive place for Docbook:
>
> http://www.docbook.org/tdg/en/html-ng/docbook.html
>
Yes, that's the page where I found the reference to
<synopfragment> but its purpose is different.
-- Massimo
---------------------------------------------------------------------
To unsubscribe, e-mail: rivet-dev-unsubscribe@tcl.apache.org
For additional commands, e-mail: rivet-dev-help@tcl.apache.org
Re: structured command synopsis
Posted by Massimo Manghi <ma...@unipr.it>.
On Fri, 9 Nov 2007 12:11:33 +0100, David Welton wrote
> Hrm... I see what you're trying to do... that would match a lot of
> the Tcl docs. However, if it looks difficult, it probably is, and docbook
> is something you can easily waste days with if you're not careful.
> I'd just add a note somewhere prominent saying "You must require the
> Rivet package with this command in order to gain access to these
> commands", or something like that.
>
I used the <note>...</note> element to mark up the warning.
'note' nicely indents the paragraph and puts an icon next
to it. I also made small changes to some paragraph in the
'examples and usage' section.
I won't send the patch on the list because the changes
are small and clear I think. I'm committing
soon if no objection is raised.
-- Massimo
---------------------------------------------------------------------
To unsubscribe, e-mail: rivet-dev-unsubscribe@tcl.apache.org
For additional commands, e-mail: rivet-dev-help@tcl.apache.org
Re: structured command synopsis
Posted by Massimo Manghi <ma...@unipr.it>.
On Fri, 9 Nov 2007 12:11:33 +0100, David Welton wrote
> Hrm... I see what you're trying to do... that would match a lot of
> the Tcl docs. However, if it looks difficult, it probably is, and docbook
> is something you can easily waste days with if you're not careful.
> I'd just add a note somewhere prominent saying "You must require the
> Rivet package with this command in order to gain access to these
> commands", or something like that.
>
I used the <note>...</note> element to mark up the warning.
'note' nicely indents the paragraph and puts an icon next
to it. I also made small changes to some paragraph in the
'examples and usage' section.
I won't send the patch on the list because the changes
are small and clear I think. I'm committing
soon if no objection is raised.
-- Massimo
---------------------------------------------------------------------
To unsubscribe, e-mail: rivet-dev-unsubscribe@tcl.apache.org
For additional commands, e-mail: rivet-dev-help@tcl.apache.org
Re: structured command synopsis
Posted by David Welton <da...@gmail.com>.
> OK, I've found out that it would be nice if
> a <cmdsynopsisinfo> element existed in the the same way
> <functionsynopisinfo> exists (it is used for specifying
> the '#include ...' directive in a C function synopsis).
>
> The only way I could visually emulate it is using the
> <sbr /> tag, which is purely presentational and therefore
> more rigid than a semantic element. Here is the patch
> for 'escape_shell_command'. David, do you think this
> may bust the rigorous XML structure of the manual :-)
Hrm... I see what you're trying to do... that would match a lot of the
Tcl docs. However, if it looks difficult, it probably is, and docbook
is something you can easily waste days with if you're not careful.
I'd just add a note somewhere prominent saying "You must require the
Rivet package with this command in order to gain access to these
commands", or something like that.
--
David N. Welton
http://www.welton.it/davidw/
http://www.dedasys.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: rivet-dev-unsubscribe@tcl.apache.org
For additional commands, e-mail: rivet-dev-help@tcl.apache.org
Re: structured command synopsis
Posted by Massimo Manghi <ma...@unipr.it>.
On Thu, 8 Nov 2007 15:29:26 +0100, David Welton wrote
>
> I'm not quite sure what you mean - you just want it to print out the
> 'package require Rivet' somewhere?
>
> This is the definitive place for Docbook:
>
> http://www.docbook.org/tdg/en/html-ng/docbook.html
>
OK, I've found out that it would be nice if
a <cmdsynopsisinfo> element existed in the the same way
<functionsynopisinfo> exists (it is used for specifying
the '#include ...' directive in a C function synopsis).
The only way I could visually emulate it is using the
<sbr /> tag, which is purely presentational and therefore
more rigid than a semantic element. Here is the patch
for 'escape_shell_command'. David, do you think this
may bust the rigorous XML structure of the manual :-)
-- Massimo
Index: rivet.xml
===================================================================
--- rivet.xml (revision 592085)
+++ rivet.xml (working copy)
@@ -1460,6 +1460,7 @@
<refsynopsisdiv>
<cmdsynopsis>
+ <command>package require Rivet</command><sbr/><sbr/>
<command>escape_shell_command</command>
<arg>string</arg>
</cmdsynopsis>
-- Massimo
---------------------------------------------------------------------
To unsubscribe, e-mail: rivet-dev-unsubscribe@tcl.apache.org
For additional commands, e-mail: rivet-dev-help@tcl.apache.org
Re: structured command synopsis
Posted by David Welton <da...@gmail.com>.
> I wonder whether DocBook has an orthodox way to have
> more structured command synopsises. The goal is
> simple: every command in the package 'Rivet' must
> show clearly that a 'package require Rivet' has
> to come in advance to the command. The tag
> 'synopisisfragment' can be the right way to do it?
> I think I can do it by trial and error, but maybe
> a DocBook expert like David has the right answer.
I'm not quite sure what you mean - you just want it to print out the
'package require Rivet' somewhere?
This is the definitive place for Docbook:
http://www.docbook.org/tdg/en/html-ng/docbook.html
--
David N. Welton
http://www.welton.it/davidw/
http://www.dedasys.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: rivet-dev-unsubscribe@tcl.apache.org
For additional commands, e-mail: rivet-dev-help@tcl.apache.org