Re: texinfo no longer covered in manual?

[Martin Kunz]

Am 11.10.2016 um 18:36 schrieb Carnë Draug:
> On 11 October 2016 at 14:11, Martin Kunz <address@hidden> wrote:
>> Hi,
>>
>> The documentation of Octave 4.0.3 (and earlier, I think) contained a
>> section "Documentation Tips" (C.4) which I consulted often, especially
>> to read on texinfo markup. I cannot find this or a comparable section in
>> 4.2.0-rc2.
>>
>> Section 2.3, "Commands for Getting Help", advices to see the section
>> "Function Files" for information about how to document self-written
>> functions, but don's see anything relevant there.
>>
>> Did this (to my mind very useful) information get lost?
> We moved most of that stuff to the Octave wiki.  The idea is to make the
> Octave manual more of a Language Reference so things like tips on how to
> write nice help text, configure emacs, Octave coding style, and mercurial
> instructions got moved to the wiki.
>
> Some of the text in the section you mention is on the wiki [1] but not all.
> There is info on how to document, but not a list of texinfo markup.  The
> old version manual is still online [2].  Do you think you may be able to
> improve on that wiki section with the type of content you would want?
>
> Carnë
>
>
> [1] http://wiki.octave.org/Help_text
> [2] 
> https://www.gnu.org/software/octave/doc/interpreter/Documentation-Tips.html

Thank you Carnë for your explanations.

I must say that I am unhappy with these changes, for various reasons.
They fall into three different categories: conceptual, personal and
visibility.

Conceptually, if you like to see the Octave manual as a language
reference, I agree that mercurial instructions and the configuration of
Emacs do not belong there. Writing nice help texts and coding style seem
less clear to me: Aren't they "close enough" to be included? But the
fact that the "help" function can parse texinfo *is* a language feature,
one that is undocumented at the moment!

Personally, I like to have all the information in one place and
available offline. Sometimes I code while travelling without internet
access and then anything on the wiki is out of my reach. But even when I
sit at my desk I prefer to search only one resource, and for "hard
facts" like the possible syntax for help texts the guideline "RTFM"
should be successful, right?

Finally, the wiki page [1] is well hidden to the average user right now.
The wiki itself is not mentioned in the GUI "Help" section, the manual
or the Octave start-up message. People may search the Octave homepage
for a wiki; they would find a link to the wiki start page under
"Support". But even when there [2], there is no reference to [1] on the
start page and neither searching for "Help" nor "Help syntax" leads them
to the right page. However, while typing "help" into the search box the
article "help text" shows up, so there is a small overall chance to find
the right page. ;-)

Taking all this into account, could we please move the Documentation
Tips back into the octave manual? They even cover more than the wiki
page (a more useful texinfo overview and a reference to nchoosek as a
good example).

[1] http://wiki.octave.org/Help_text
[2] http://wiki.octave.org/GNU_Octave_Wiki
[3]
https://www.gnu.org/software/octave/doc/interpreter/Documentation-Tips.html