Better documentation search

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Better documentation search

John Swensen-3
I am considering going back and working on incorporating the Xapian-based (see http://www.ibm.com/developerworks/opensource/library/os-xapianomega/index.html?cmp=dw&cpb=dwope&ct=dwnew&cr=dwnen&ccy=zz&csr=110410 for info on how the database is generated from a collection of HTML files and how to access them from the API) HTML documentation search functionality that I have in OctaveDE into the help browser for the QT IDE. It ended up being a really, really fast live search method that I really liked and think it would be a good addition to the QT IDE. I realize it adds one more dependency for the IDE, but think it might be worth it. Of course, it will just be a patch so the powers that be can decide whether it is worth it. If I remember correctly, the database containing all the metadata for searching was about 9MB for all of the main Octave functions and all of OctaveForge. However, I have a few questions:

1) Is there HTML documentation that is part of all the release packages? If would this be preferred over the OctaveForge documentation layout.
2) Is there a zipped up version of the OctaveForge documentation somewhere? I could use something like HTTrack to deep scrape the whole site, but if this is downloadable somewhere that would be better. Or, how is this generated?

John Swensen

Reply | Threaded
Open this post in threaded view
|

Re: Better documentation search

Carnë Draug
On 19 November 2013 04:50, John Swensen <[hidden email]> wrote:
> [...]
> 1) Is there HTML documentation that is part of all the release packages? If
> would this be preferred over the OctaveForge documentation layout.

Each release is done with the entire manual in HTML. It also has
entries for each of the individual functions which actually just links
to the manual (every core function should have an entry in the
manual).

> 2) Is there a zipped up version of the OctaveForge documentation somewhere?

No. But you can easily generate it yourself with the generate_html package.

> I could use something like HTTrack to deep scrape the whole site, but if
> this is downloadable somewhere that would be better. Or, how is this
> generated?

There's a function in the generate_html that generates HTML pages for
each of the functions. It's up to the package maintainers to do this
for each release they prepare (I do it for Octave core). When the
release is done I upload the folder to the root of the Octave Forge
webserver. The rest is done by php scripts. Rather than scrape the
whole site, you can limit the search to the alphabetical list [1]. A
better way to do this, because errors in the help text sometimes mess
up that list, would be:

1) parse the list of packages[2] (and add octave core to the list)
2) for each package read the files
http://octave.sourceforge.net/PKG_NAME/function_names_X (the X at the
end are the letters of the alphabet) which list all functions
belonging to that package
3) get the HTML documentation from
http://octave.sourceforge.net/PKG_NAME/FUNCTION_NAME.html

I may have understood it wrong, but your suggestion is to have the
documentation for each function as HTML already distributed with
Octave to search faster? If that's the case, then:

* we have the documentation in Texinfo which can be used to generate
HTML documentation easily. And we have the lookfor function which
searches through all the documentation of all functions (even the
unreleased stuff and local to the user). Can we use this two?
* you can't do that for Octave Forge packages because they are
independent of Octave core releases.

Carnë

[1] http://octave.sourceforge.net/functions_by_alpha.php
[2] http://octave.sourceforge.net/packages.php
Reply | Threaded
Open this post in threaded view
|

Re: Better documentation search

Richard Kirk
Thanks Carnë.

I had never found the 'lookfor' command. I always thought there ought to be a better way of looking for a command if you have no idea what it's name was. The 'octave' naming style is pretty compact, and it is sometimes hard to guess.

If you do 'help lookfor' then the help message ends with...
     See also: help, doc, which.

Perhaps the straight 'help' reply should have a similar last line...
     See also: doc, which, lookfor

That would put people like me on the right track.

Cheers.
Richard Kirk
Reply | Threaded
Open this post in threaded view
|

Re: Better documentation search

Carnë Draug
On 16 April 2014 08:46, Richard KIrk <[hidden email]> wrote:

>
> I had never found the 'lookfor' command. I always thought there ought to be
> a better way of looking for a command if you have no idea what it's name
> was. The 'octave' naming style is pretty compact, and it is sometimes hard
> to guess.
>
> If you do 'help lookfor' then the help message ends with...
>      See also: help, doc, which.
>
> Perhaps the straight 'help' reply should have a similar last line...
>      See also: doc, which, lookfor
>
> That would put people like me on the right track.

It does. Under Octave 3.8.1:

    octave:3> help help
         [...]
         See also: doc, lookfor, which.

Carnë

Reply | Threaded
Open this post in threaded view
|

Re: Better documentation search

Richard Kirk

On 17 Apr 2014, at 21:21, Carnë Draug wrote:

> On 16 April 2014 08:46, Richard KIrk <[hidden email]> wrote:
>>
>> I had never found the 'lookfor' command. I always thought there ought to be
>> a better way of looking for a command if you have no idea what it's name
>> was. The 'octave' naming style is pretty compact, and it is sometimes hard
>> to guess.
>>
>> If you do 'help lookfor' then the help message ends with...
>>     See also: help, doc, which.
>>
>> Perhaps the straight 'help' reply should have a similar last line...
>>     See also: doc, which, lookfor
>>
>> That would put people like me on the right track.
>
> It does. Under Octave 3.8.1:
>
>    octave:3> help help
>         [...]
>         See also: doc, lookfor, which.

That's 'help help' which I didn't think to try. I got a message with 'help' and assumed that was it. 'help help' is obvious in hindsight, thought it reminds me of 'Piglet meets a Heffalump' :).

Thanks.
Richard Kirk