Re: Documentation in the GUI

[Torsten]

On 06.02.2015 22:02, Daniel J Sebald wrote:
> On 02/06/2015 10:55 AM, Rik wrote:
>> On 02/05/2015 09:00 AM, address@hidden wrote:
>>> Subject:
>>> Re: Documentation for the GUI
>>> From:
>>> Daniel J Sebald <address@hidden>
>>> Date:
>>> 02/04/2015 10:19 PM
>>>
>>> To:
>>> Torsten <address@hidden>
>>> CC:
>>> address@hidden
>>>
>>> List-Post:
>>> <mailto:address@hidden>
>>> Content-Transfer-Encoding:
>>> quoted-printable
>>> Precedence:
>>> list
>>> MIME-Version:
>>> 1.0
>>> References:
>>> <address@hidden>
>>> <address@hidden> <address@hidden>
>>> <address@hidden> <address@hidden>
>>> In-Reply-To:
>>> <address@hidden>
>>> Message-ID:
>>> <address@hidden>
>>> Content-Type:
>>> text/plain; charset=UTF-8; format=flowed
>>> Message:
>>> 1
>>>
>>>
>>> On 02/05/2015 12:03 AM, Torsten wrote:
>>>> On 05.02.2015 06:44, Michael Godfrey wrote:
>>>>>
>>>>> On 02/05/2015 12:10 AM, Daniel J Sebald wrote:
>>>>>> On 02/02/2015 09:14 AM, Jordi Gutiérrez Hermoso wrote:
>>>>>>> On Sat, 2015-01-31 at 19:17 +1100, Svetlana Tkachenko wrote:
>>>>>>>> As the intent is to release the GUI to users at a point, where is
>>>>>>>> the current documentation for it?
>>>>>>>
>>>>>>> There is none.
>>>>>>>
>>>>>>> Can you help us write it?
>>>>>>
>>>>>> Something to consider:  Qt has a facility called Qt-Assistant for
>>>>>> help.  It's very similar to what is called a HelpBook in Windows.
>>>>>> (That very familiar layout with the table of contents on the left
>>>>>> side
>>>>>> for quick access, also searching.  Even Acrobat Reader uses that look
>>>>>> and feel.) I just used Qt-Assistant for the gnuplot Qt terminal.  The
>>>>>> Octave help code would need to be translated to the Qt-Assistant
>>>>>> format and bundled, but it doesn't prove too difficult.  There are a
>>>>>> few commands for Qt code to interact with the Qt-Assistant, say,
>>>>>> jumping to certain locations in help as directed by the code in the
>>>>>> GUI.  Just letting you know that's an option.
>>>>>>
>>>>>> Dan
>>>>> Since as it is now, you can bring up pages of the manual within the
>>>>> GUI
>>>>> why not just update
>>>>> the Manual, which has to be done anyhow?
>>>>>
>>>>> Michael
>>>>>
>>>>
>>>> I have been looking for a tool that can automatically convert the
>>>> octave
>>>> documentation (texinfo or html) into a Qt help project (.qhp) with
>>>> index
>>>> etc. since some time but wasn't successful so far. Sure we can
>>>> translate
>>>> it manually but I think we need this to be done automatically during
>>>> the
>>>> build process. Maybe I am missing something and it is not that
>>>> complicated.
>>>
>>> I think if one looks at the contents of the HTML documentation,
>>> they'll see that there probably already is a quasi-organization based
>>> upon the HTML formatting and maybe in Octave's case a numbering system
>>> to go along with that.  It's probably not too difficult to write
>>> something that runs through the hierarchy, beginning with
>>>
>>> doc/liboctave/liboctave.html/index.html
>>>
>>> searching for link references.  Could even use an octave script to
>>> make it a little easier.
>>>
>>> But you're right.  An existing utility would make life easier.  I
>>> can't recall seeing one.
>>>
>>> Dan
>>
>> I'm quite proficient in Perl and if the input/output formats are not too
>> different then it is an easy task to write up a protocol converter.
>>
>> Larger question, is this what we want to do?  Move all documentation in
>> the GUI over to Qt-Assistant?
> 
> No strong opinion one way or another here.  The only thing I'd say is
> that the documentation window currently fills up quickly with tabs if
> browsing through the HTML help.
> 

Using Qt-Assistant (or embedding help with the Qt help engine) would
save the effort for manually searching keywords, page handling etc. And
as the pages html, it can also handle images.

Torsten