| IDLDoc Bandwagon [message #72510] |
Mon, 20 September 2010 16:48  |
David Fanning
Messages: 11724
Registered: August 2001
|
Senior Member |
|
|
Folks,
I have been wanting to get on the IDLDoc bandwagon
for awhile now. But I have never been able to successfully
get reasonable looking output from any of my (apparently
feeble) attempts to get it to work.
Today I downloaded the very latest from Mike's web page,
and spent most of the afternoon trying one combination
after the other. Nearly all of my attempts, no matter
what I set the FORMAT_STYLE keyword to, end up looking
like a dog's dish with all my comments slammed together
in a single paragraph.
I'm usually no good at figuring these kinds of things out,
but I have spent enough time on it that I would have
expected to be *somewhere* by now. Line endings seem
somehow to be involved, so I thought I would just ask,
has anyone gotten this to work on a Windows machine?
Cheers,
David
--
David Fanning, Ph.D.
Fanning Software Consulting, Inc.
Coyote's Guide to IDL Programming: http://www.dfanning.com/
Sepore ma de ni thui. ("Perhaps thou speakest truth.")
|
|
|
|
| Re: IDLDoc Bandwagon [message #72639 is a reply to message #72510] |
Tue, 21 September 2010 14:32  |
David Fanning
Messages: 11724
Registered: August 2001
|
Senior Member |
|
|
Michael Galloy writes:
> Yes, in "rst" markup this would be:
>
>
> ; The `MinMax` routine gives the range of a variable::
> ;
> ; IDL> a = findgen(11)
> ; IDL> MinMax, a
> ; MinMax: 0 10
>
> You need a blank line between the '::' and the code start as well as an
> indent for the code.
Oh, perfect! Thanks. :-)
Cheers,
David
--
David Fanning, Ph.D.
Fanning Software Consulting, Inc.
Coyote's Guide to IDL Programming: http://www.dfanning.com/
Sepore ma de ni thui. ("Perhaps thou speakest truth.")
|
|
|
|
| Re: IDLDoc Bandwagon [message #72640 is a reply to message #72510] |
Tue, 21 September 2010 14:12 |
Michael Galloy
Messages: 1114
Registered: April 2006
|
Senior Member |
|
|
On 9/21/10 11:17 am, David Fanning wrote:
> Michael Galloy writes:
>
>> Yes, you can put file-level comments at the beginning of the file, i.e.,
>> comments between ;+ and ;- that are not immediately next to a routine
>> header are "file-level." I generally put documentation about each
>> routine in the header right next to that routine and file-level stuff
>> about the whole file like what the "public" routines in the file are in
>> the file-level comments.
>
> OK, I'm getting to something I can live with, but I want to
> move to the "rst" format. In this format, how can I put multiple
> line examples into the documentation? For example, something
> like this:
>
> IDL> a = findgen(11)
> IDL> MinMax, a
> MinMax: 0 10
>
> Also, would it be possible to put these kind of code fragments
> in some kind of "code" type font?
Yes, in "rst" markup this would be:
; The `MinMax` routine gives the range of a variable::
;
; IDL> a = findgen(11)
; IDL> MinMax, a
; MinMax: 0 10
You need a blank line between the '::' and the code start as well as an
indent for the code. You don't need text explanation if you don't want:
; ::
;
; IDL> a = findgen(11)
; IDL> MinMax, a
; MinMax: 0 10
Mike
--
www.michaelgalloy.com
Research Mathematician
Tech-X Corporation
|
|
|
|
| Re: IDLDoc Bandwagon [message #72642 is a reply to message #72510] |
Tue, 21 September 2010 10:17 |
David Fanning
Messages: 11724
Registered: August 2001
|
Senior Member |
|
|
Michael Galloy writes:
> Yes, you can put file-level comments at the beginning of the file, i.e.,
> comments between ;+ and ;- that are not immediately next to a routine
> header are "file-level." I generally put documentation about each
> routine in the header right next to that routine and file-level stuff
> about the whole file like what the "public" routines in the file are in
> the file-level comments.
OK, I'm getting to something I can live with, but I want to
move to the "rst" format. In this format, how can I put multiple
line examples into the documentation? For example, something
like this:
IDL> a = findgen(11)
IDL> MinMax, a
MinMax: 0 10
Also, would it be possible to put these kind of code fragments
in some kind of "code" type font?
Thanks,
David
--
David Fanning, Ph.D.
Fanning Software Consulting, Inc.
Coyote's Guide to IDL Programming: http://www.dfanning.com/
Sepore ma de ni thui. ("Perhaps thou speakest truth.")
|
|
|
|
| Re: IDLDoc Bandwagon [message #72645 is a reply to message #72510] |
Tue, 21 September 2010 07:16 |
Michael Galloy
Messages: 1114
Registered: April 2006
|
Senior Member |
|
|
On 9/20/10 10:30 pm, Paulo Penteado wrote:
> On Sep 21, 1:20 am, David Fanning<n...@dfanning.com> wrote:
>> Yes, I have a question about that. What do you do in the
>> case of a large file with many modules? The module I want
>> to document is, of course, at the bottom of the file. And
>> yet I want the documentation to appear at the top of the
>> file. How would you handle something like that?
>
> Maybe with hidden or private tags to suppress the other routines?
>
>
>> Also, I want to have the copyright notice (as some significant
>> amount of text) in the file. What would be the best way to
>> handle that? There really isn't a category for that, and
>> it seems a little strange to put it someplace like after
>> the procedure definition statement (which would follow
>> immediately after the documentation) and before the first
>> line of code in the procedure.
>
> There is a copyright tag, and it could go on the file-level comments.
> Or in an overview file. Am I missing something?
Yes, you can put file-level comments at the beginning of the file, i.e.,
comments between ;+ and ;- that are not immediately next to a routine
header are "file-level." I generally put documentation about each
routine in the header right next to that routine and file-level stuff
about the whole file like what the "public" routines in the file are in
the file-level comments.
For the copyright notice, I either put it in normal comments (without ;+
and ;-) right at the top of the file or I put it in the :Copright: tag.
Since the :Copyright: tag is not available in the IDL format, I would
just put it in normal comments.
Mike
--
www.michaelgalloy.com
Research Mathematician
Tech-X Corporation
|
|
|
|
| Re: IDLDoc Bandwagon [message #72646 is a reply to message #72510] |
Tue, 21 September 2010 07:02 |
Michael Galloy
Messages: 1114
Registered: April 2006
|
Senior Member |
|
|
On 9/20/10 10:23 pm, Paulo Penteado wrote:
> On Sep 21, 1:16 am, Paulo Penteado<pp.pente...@gmail.com> wrote:
>> On Sep 21, 12:54 am, Michael Galloy<mgal...@gmail.com> wrote:
>>
>>> It's painful to convert existing files, so individual files can specify
>>> their own FORMAT_STYLE/MARKUP_STYLE by putting a "docformat" comment on
>>> the *first line* of the file, like:
>>
>>> ; docformat = 'rst rst'
>>
>>> or
>>
>>> ; docformat = 'IDL preformatted'
>>
>> I had not noticed that the markup style could fix the newlines for old
>> comments.
>>
>> What I have been using, to make the old files work unaltered, is to
>> specify fortmat_style='IDL' in the call to IDLDoc, and always put the
>> docformat on the new files, to override the IDL format.
>
> By the way, I noticed that using fortmat_style='IDL' in the IDLDoc
> call seems to supress the contents of the overview file. Is this
> intended?
Not everything is supported in the "legacy styles." I would like to, but
I just haven't finished everything for them. Expect new features in the
rst format/markup styles, but not really anything new in the IDL/IDLdoc
format styles.
Mike
--
www.michaelgalloy.com
Research Mathematician
Tech-X Corporation
|
|
|
|
| Re: IDLDoc Bandwagon [message #72652 is a reply to message #72510] |
Mon, 20 September 2010 21:53 |
David Fanning
Messages: 11724
Registered: August 2001
|
Senior Member |
|
|
Paulo Penteado writes:
> There is a copyright tag, and it could go on the file-level comments.
> Or in an overview file. Am I missing something?
I don't know. Maybe I'm doing something wrong. I can't seem
to get IDLDoc to pick up any of the copyright text. But
then, again, I can't get it to pick up the MODIFICATION HISTORY
text either. (Although at one time I had that information
in the output. And I thought I was running the very same
code!!)
Too many new things today, probably. :-(
Cheers,
David
--
David Fanning, Ph.D.
Fanning Software Consulting, Inc.
Coyote's Guide to IDL Programming: http://www.dfanning.com/
Sepore ma de ni thui. ("Perhaps thou speakest truth.")
|
|
|
|
| Re: IDLDoc Bandwagon [message #72653 is a reply to message #72510] |
Mon, 20 September 2010 21:30 |
penteado
Messages: 866
Registered: February 2018
|
Senior Member
Administrator |
|
|
On Sep 21, 1:20 am, David Fanning <n...@dfanning.com> wrote:
> Yes, I have a question about that. What do you do in the
> case of a large file with many modules? The module I want
> to document is, of course, at the bottom of the file. And
> yet I want the documentation to appear at the top of the
> file. How would you handle something like that?
Maybe with hidden or private tags to suppress the other routines?
> Also, I want to have the copyright notice (as some significant
> amount of text) in the file. What would be the best way to
> handle that? There really isn't a category for that, and
> it seems a little strange to put it someplace like after
> the procedure definition statement (which would follow
> immediately after the documentation) and before the first
> line of code in the procedure.
There is a copyright tag, and it could go on the file-level comments.
Or in an overview file. Am I missing something?
|
|
|
|
| Re: IDLDoc Bandwagon [message #72654 is a reply to message #72510] |
Mon, 20 September 2010 21:23 |
penteado
Messages: 866
Registered: February 2018
|
Senior Member
Administrator |
|
|
On Sep 21, 1:16 am, Paulo Penteado <pp.pente...@gmail.com> wrote:
> On Sep 21, 12:54 am, Michael Galloy <mgal...@gmail.com> wrote:
>
>> It's painful to convert existing files, so individual files can specify
>> their own FORMAT_STYLE/MARKUP_STYLE by putting a "docformat" comment on
>> the *first line* of the file, like:
>
>> ; docformat = 'rst rst'
>
>> or
>
>> ; docformat = 'IDL preformatted'
>
> I had not noticed that the markup style could fix the newlines for old
> comments.
>
> What I have been using, to make the old files work unaltered, is to
> specify fortmat_style='IDL' in the call to IDLDoc, and always put the
> docformat on the new files, to override the IDL format.
By the way, I noticed that using fortmat_style='IDL' in the IDLDoc
call seems to supress the contents of the overview file. Is this
intended?
|
|
|
|
| Re: IDLDoc Bandwagon [message #72655 is a reply to message #72510] |
Mon, 20 September 2010 21:20 |
David Fanning
Messages: 11724
Registered: August 2001
|
Senior Member |
|
|
Michael Galloy writes:
> But, in the meantime, you are correct, the FORMAT_STYLE and MARKUP_STYLE
> determine how the comments are formatted in the output. Looking at some
> of the code in your library, it looks like you probably should use
> FORMAT_STYLE='IDL' and MARKUP_STYLE='preformatted' (it won't look good,
> but should be readable). The MARKUP_STYLE='preformatted' will make
> linefeeds significant.
I have finally managed to get something that looks hopeful,
but, yes, it took me quite a while to find the right page
with the information I needed. I think the new documentation
will be well received. :-)
> You will also need to make the comment header
> (i.e., the part between ;+ and ;-) be next to the routine prototype (the
> pro/function line), like:
Yes, I have a question about that. What do you do in the
case of a large file with many modules? The module I want
to document is, of course, at the bottom of the file. And
yet I want the documentation to appear at the top of the
file. How would you handle something like that?
Also, I want to have the copyright notice (as some significant
amount of text) in the file. What would be the best way to
handle that? There really isn't a category for that, and
it seems a little strange to put it someplace like after
the procedure definition statement (which would follow
immediately after the documentation) and before the first
line of code in the procedure.
The copyright thing is on my mind today, as I am in the
process of moving the Coyote and Catalyst Libraries over
to GoogleCode, so people can access it via a Subversion
repository.
Thanks for the help!
Cheers,
David
--
David Fanning, Ph.D.
Fanning Software Consulting, Inc.
Coyote's Guide to IDL Programming: http://www.dfanning.com/
Sepore ma de ni thui. ("Perhaps thou speakest truth.")
|
|
|
|
| Re: IDLDoc Bandwagon [message #72656 is a reply to message #72510] |
Mon, 20 September 2010 21:16 |
penteado
Messages: 866
Registered: February 2018
|
Senior Member
Administrator |
|
|
On Sep 21, 12:54 am, Michael Galloy <mgal...@gmail.com> wrote:
> It's painful to convert existing files, so individual files can specify
> their own FORMAT_STYLE/MARKUP_STYLE by putting a "docformat" comment on
> the *first line* of the file, like:
>
> ; docformat = 'rst rst'
>
> or
>
> ; docformat = 'IDL preformatted'
I had not noticed that the markup style could fix the newlines for old
comments.
What I have been using, to make the old files work unaltered, is to
specify fortmat_style='IDL' in the call to IDLDoc, and always put the
docformat on the new files, to override the IDL format.
|
|
|
|
| Re: IDLDoc Bandwagon [message #72657 is a reply to message #72510] |
Mon, 20 September 2010 20:54 |
Michael Galloy
Messages: 1114
Registered: April 2006
|
Senior Member |
|
|
On 9/20/10 5:48 pm, David Fanning wrote:
> Folks,
>
> I have been wanting to get on the IDLDoc bandwagon
> for awhile now. But I have never been able to successfully
> get reasonable looking output from any of my (apparently
> feeble) attempts to get it to work.
>
> Today I downloaded the very latest from Mike's web page,
> and spent most of the afternoon trying one combination
> after the other. Nearly all of my attempts, no matter
> what I set the FORMAT_STYLE keyword to, end up looking
> like a dog's dish with all my comments slammed together
> in a single paragraph.
>
> I'm usually no good at figuring these kinds of things out,
> but I have spent enough time on it that I would have
> expected to be *somewhere* by now. Line endings seem
> somehow to be involved, so I thought I would just ask,
> has anyone gotten this to work on a Windows machine?
One thing that has slowed me down on the most recent release of IDLdoc
is that it will have actual documentation: both a tutorial and a
reference manual! Hopefully, these will help people learn how to get the
comments formatted usefully.
But, in the meantime, you are correct, the FORMAT_STYLE and MARKUP_STYLE
determine how the comments are formatted in the output. Looking at some
of the code in your library, it looks like you probably should use
FORMAT_STYLE='IDL' and MARKUP_STYLE='preformatted' (it won't look good,
but should be readable). The MARKUP_STYLE='preformatted' will make
linefeeds significant. You will also need to make the comment header
(i.e., the part between ;+ and ;-) be next to the routine prototype (the
pro/function line), like:
;+
; NAME:
; BITGET
;
; PURPOSE:
;
; Returns the bit value (0 or 1) of a specified bit in a supplied
; number.
;
; AUTHOR:
;
; FANNING SOFTWARE CONSULTING
; David Fanning, Ph.D.
; 1645 Sheely Drive
; Fort Collins, CO 80526 USA
; Phone: 970-221-0438
; E-mail: davidf@dfanning.com
; Coyote's Guide to IDL Programming: http://www.dfanning.com
;
; CATEGORY:
;
; Utilities
;
; CALLING SEQUENCE:
;
; bitValue = BitGet(number, bit)
;
; INPUT_PARAMETERS:
;
; number: The input number. Should be a scalar integer.
; If not, it is converted to
; one by rounding.
;
; bit: The number of the bit you are interested in. A
; value between 0 and 63.
; If not supplied, all 64 bit values of the
; number are returned. May be an array of bit
; numbers.
;
; OUTPUT_PARAMETERS:
;
; bitValue: The value, 0 or 1, of the specified bit in the
; number.
;
; KEYWORDS:
;
; SILENT: If set, suppresses informational messages
; regarding rounding operations.
;
; MODIFICATION HISTORY:
;
; Written by David W. Fanning, 14 June 2006.
;-
FUNCTION BitGet, value, bit, SILENT=silent
Note, I recommend using FORMAT_STYLE='rst', MARKUP_STYLE='rst' for new
comments, in which case the header would look like:
;+
; Returns the bit value (0 or 1) of a specified bit in a supplied
; number.
;
; :Categories:
; utilities
;
; :Author:
; ::
;
; FANNING SOFTWARE CONSULTING
; David Fanning, Ph.D.
; 1645 Sheely Drive
; Fort Collins, CO 80526 USA
; Phone: 970-221-0438
; E-mail: davidf@dfanning.com
; Coyote's Guide to IDL Programming: http://www.dfanning.com
;
; :History:
; Written by David W. Fanning, 14 June 2006.
;
; :Params:
; value : in, required, type=integer
; The input number. Should be a scalar integer. If not, it is
; converted to one by rounding.
; bit : in, optional, type=integer
; The value, 0 or 1, of the specified bit in the number.
;
; :Keywords:
; silent : in, optional, type=boolean
; If set, suppresses informational messages regarding rounding
; operations.
;-
FUNCTION BitGet, value, bit, SILENT=silent
It's painful to convert existing files, so individual files can specify
their own FORMAT_STYLE/MARKUP_STYLE by putting a "docformat" comment on
the *first line* of the file, like:
; docformat = 'rst rst'
or
; docformat = 'IDL preformatted'
Anyway, I hope to have something a bit more complete by the way of
documentation out soon.
Mike
--
www.michaelgalloy.com
Research Mathematician
Tech-X Corporation
|
|
|
|
| Re: IDLDoc Bandwagon [message #72658 is a reply to message #72510] |
Mon, 20 September 2010 18:29 |
penteado
Messages: 866
Registered: February 2018
|
Senior Member
Administrator |
|
|
On Sep 20, 10:27 pm, Paulo Penteado <pp.pente...@gmail.com> wrote:
> Yes, I have seen that on old comments. Line endings in a block are
> disregarded. To force a line change, you need to leave a blank line.
"blank line" meaning a line with just the initial ";", of course.
|
|
|
|
| Re: IDLDoc Bandwagon [message #72659 is a reply to message #72510] |
Mon, 20 September 2010 18:27 |
penteado
Messages: 866
Registered: February 2018
|
Senior Member
Administrator |
|
|
On Sep 20, 8:48 pm, David Fanning <n...@dfanning.com> wrote:
> Today I downloaded the very latest from Mike's web page,
> and spent most of the afternoon trying one combination
> after the other. Nearly all of my attempts, no matter
> what I set the FORMAT_STYLE keyword to, end up looking
> like a dog's dish with all my comments slammed together
> in a single paragraph.
>
> I'm usually no good at figuring these kinds of things out,
> but I have spent enough time on it that I would have
> expected to be *somewhere* by now. Line endings seem
> somehow to be involved, so I thought I would just ask,
> has anyone gotten this to work on a Windows machine?
Yes, I have seen that on old comments. Line endings in a block are
disregarded. To force a line change, you need to leave a blank line.
|
|
|
|
comp.lang.idl-pvwave archive
Members
Search
Help
Login
Home
