fre, 12 02 2010 kl. 22:46 +0100, skrev Philip Nienhuis:
> Anyway that's what I also found, but I figured that solution might still
> be fragile - there are cases where it might fail, like otherwise useful
> abbreviations, viz. e.g. etc. (pun intended.)
This will always be a bit "hacky". I don't think it'll ever be possible
to write a computer program that determines when a sentence is
completed.
> The situation would improve if stricter requirements would be imposed on
> that first sentence, like:
> - Max 80 characters incl. the last dot ;-) (BTW isn't this a bit too
> short?)
The function is also used in 'lookfor' to generate the list of matching
functions. This is where the 80 char limit comes from as this matches
the most common terminal size. We can increase the number in the
'generate_html' package, but I don't think it should be much larger, as
the generated lists should be fairly concise.
> - MUST end with one or two newline(s) (or space + newline(s))
I'd rather not enforce a specific format as people tend to be quite
sloppy wrt. documentation.
> - May contain only a concise & general description of what the function
> file does
> (Hmmm I did trespass these requirements myself)
I think this is the general idea, but I don't think that many authors
actually write the documentation this way :-(
> BTW it is function file get_first_help_sentence.m, plaintext subfunction
> (written by you BTW) in the core octave Help package where this logic is
> implemented. I've already looked at how to mend it but an elegant fix is
> not as straightforward (for me) as I figured it would be (ugly hacks are
> easier).
I don't think an elegant solution to this problem is feasibly. What I
have written is quite a hack, but it works most of the time. We could in
principle introduce a new texinfo macro that marks the first sentence,
i.e. something like
@first_sentence{Rotate an image around the center by a given angle.}
This would also allow us to apply a different style to the first
sentence (not sure if we would actually want to do that, though).
This approach, however, requires changes to core Octave, and to be
honest I'm not so sure it's actually a good idea...
Søren
------------------------------------------------------------------------------
SOLARIS 10 is the OS for Data Centers - provides features such as DTrace,
Predictive Self Healing and Award Winning ZFS. Get Solaris 10 NOW
http://p.sf.net/sfu/solaris-dev2dev
_______________________________________________
Octave-dev mailing list
Octave-dev@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/octave-dev
