More explicitly document the two kinds of syntaxes

[catch22]

It appears that the demands of the Octave project lead to two diverging syntaxes, so I think we should be more explicit in the documentation. What would be good names?

1. >>/simple/basic/original/doctest syntax

   This is the one that emulates the behavior of an Octave/Matlab session.

2. (Octave) Texinfo syntax?

   This is the Texinfo syntax that uses more semantic markup.

[cbm755]

hmm, I think my doc revisions in #101 took the opposite approach: less explicit, sorry :)

But note I did at least explicitly note the two behaviours at the end of help doctest... is this enough for now?

[catch22]

I've merged #101, but let's maybe leave this issue open? Here are some possible ideas of what we could do about this bug:

• expand the doctest help string
• provide a "tutorial" document (properly linked on the OctaveForge package homepage). it could even have a section or document targeted towards Octave core devs interested in making their documentation work with doctest
• provide a number of idiomatic examples in /examples

[oheim]

Number 1 is a “copy” of the octave session and can be easily copied into the documentation. You could call it “diary style”, because it resembles the output of the diary command, which records your session.

Number 2 uses a different markup (instead of marking the input, it marks the output and discriminates between return values and console output) and is easier to copy back into a new octave session, because you don't have to cut away the >> markers. This has nothing to do with Texinfo or plain text documentation in the first place, because you can also choose style 1 with Texinfo. However, style 2 is the intended style of Texinfo and (officially) Octave. Thus, you could certainly call it “Octave/Texinfo style” to make clear it is the official style.

On the tutorial document: Since we would not want to have redundant style guides available, you can probably create patches for https://www.gnu.org/software/octave/doc/interpreter/Documentation-Tips.html to describe the best practice for writing documentation in more detail.

Particular hints for pitfalls with doctest (ascii art in @example blocks, etc.) could be described in a package documentation (this will become a dedicated section of the Octave manual after an integration into core). The documentation string for the doctest command has exceeded the tl;dr barrier already. Anything beyond basic function invocation and command line options can certainly be made more accessible in a well structured document.

[cbm755]

easier to copy back into a new octave session, because you don't have to cut away the >> markers.

at least in HTML doc, I had thoughts to render >> grey and non-selectable (like one sees with line numbers on some websites).

+1 for "diary style" terminology.

+1 for docstring of doctest.m being a bit tl;dr: I tried to shorten in my last edit but agree, a well-structured manual elsewhere (doesn't have to be long) would be good...

[oheim]

I had thoughts to render >> grey and non-selectable

I did this once for examples in the wiki. It has been a burden to maintain. In TexInfo you could use a @prompt{} macro, but you probably have to redefine in in every function header.

[catch22]

I also like the "diary style" terminology.

This has nothing to do with Texinfo or plain text documentation in the first place, because you can also choose style 1 with Texinfo.

There certainly is some correlation, as you cannot choose style 2 without Texinfo ;) At any rate: My understanding is that we support the three following options:

1. diary style in plaintext comments
2. diary style in Texinfo @example sections
3. explicit style (@result/@print) in Texinfo @example sections

(and even mixtures of 2+3, as is being discussed in #107). From this perspective, "Octave Texinfo style" might not the optimal terminology for the third option, unless we decide to bunch together style 2+3 (which might actually be a good idea).

However we choose to call these syntaxes, we need document these three options. For this, expanding the docstring would probably be the most straightforward option, while adding a separate tutorial document might perhaps be more appropriate, as I believe that our primary goal right now should be to make doctest as accessible as possible so that other Octave developers will adopt it. Such a document will also be mostly orthogonal to the Octave Texinfo style guide, but rather discuss the syntax accepted by Doctest. That is, it would be more in line with https://www.gnu.org/software/octave/doc/interpreter/Test-Functions.html, which is quite the tl;dr precedent... I'll leave the choice of format to whoever goes ahead and adds a first draft 😄

We can think about how to optimally merge our documentation into the Octave one when the time has come. Right now, we should strive for our package to be well-documented on its own & accessible to interested (core) developers.

[cbm755]

I re-read the end of help doctest again and its fairly explicit about diary style and Octave/Texinfo Style. Nothing to do here for 0.4.1, dropping milestone.

But leaving open as discussion of manual etc is relevant,

[catch22]

Closing this after your changes to help doctest and since #129 is our main documentation issue.