From: Janus Weil on

> > [No this is not a criticism of gcc or all the hard work that has gone
> > into it. But someone else must find the documentation somewhat daunting.]
>
> I'd like to see gfortran.pdf have some screenshots and more examples.

Screenshots? Are you serious? Why would the gfortran manual need
screenshots? That's ridiculous.

Examples are always useful, though (in particular for beginners).


> I think documentation is simply one of those things that implementors
> don't want to do so much, yet this scaffolding is necessary.

In the case of GCC it's also one of the things that many users can
easily contribute to, without having any knowledge of the actual GCC
source code.

If you find something in the gfortran manual that is documented
insufficiently (or wrongly), you can at least raise this on the
gfortran mailing list to draw the developers' attention to it. Or, if
you know how to improve it, you can even post a small documentation
patch.

Cheers,
Janus
From: Uno on
Janus Weil wrote:
>>> [No this is not a criticism of gcc or all the hard work that has gone
>>> into it. But someone else must find the documentation somewhat daunting.]
>> I'd like to see gfortran.pdf have some screenshots and more examples.
>
> Screenshots? Are you serious? Why would the gfortran manual need
> screenshots? That's ridiculous.
>
> Examples are always useful, though (in particular for beginners).


There is nothing visual about this help manual. It is a common unix
disease to think that man man is the way to begin documentation.

What is the thing that documentation has that companies pay good money
for? A visual or aural component. That's why I used to go with Microsoft.


>
>
>> I think documentation is simply one of those things that implementors
>> don't want to do so much, yet this scaffolding is necessary.
>
> In the case of GCC it's also one of the things that many users can
> easily contribute to, without having any knowledge of the actual GCC
> source code.
>
> If you find something in the gfortran manual that is documented
> insufficiently (or wrongly), you can at least raise this on the
> gfortran mailing list to draw the developers' attention to it. Or, if
> you know how to improve it, you can even post a small documentation
> patch.

I guess, before I do that, I would want to know if there is any appetite
for what I might do. I've been on the gfortran mailing list before for
several months, but I didn't understand much of it. For example, I
still don't know what a trunk is. I'm inclined to believe that it is to
evoke the tree metaphor. It could also be the back end of a car. I
asked this question on this mailing list and didn't receive a response
that I could discern. It was my first experience with a mailing list
and would only be called successful if lurking were the objective.

I also consider it a distinct possibility that Jerry Delisle, Tobias
Burnus, mathematican steve etc. don't want me fouling up gfortran.pdf
with my puerile pictures. I am becoming quite adept with GIMP, and can
make a clean .jpg image of a size appropriate for the pdf format that is
less a 100 k.

The topics I could cover well are
1) How to use gfortran on windows
2) How to use gfortran off a memory stick

Anyways, breakfast calls.
Cheers,
--
Uno
From: nmm1 on
In article <8blmv7FbfsU1(a)mid.individual.net>, Uno <merrilljensen(a)q.com> wrote:
>Janus Weil wrote:
>>>> [No this is not a criticism of gcc or all the hard work that has gone
>>>> into it. But someone else must find the documentation somewhat daunting.]
>>> I'd like to see gfortran.pdf have some screenshots and more examples.
>>
>> Screenshots? Are you serious? Why would the gfortran manual need
>> screenshots? That's ridiculous.
>>
>> Examples are always useful, though (in particular for beginners).
>
>There is nothing visual about this help manual. It is a common unix
>disease to think that man man is the way to begin documentation.

While that is true, the textual aspect of man is not one of its
defects for semi-technical or technical information.

>What is the thing that documentation has that companies pay good money
>for? A visual or aural component. That's why I used to go with Microsoft.

And you are intending to program in a 'third-generation language'
like Fortran? The mind boggles.


Regards,
Nick Maclaren.
From: dpb on
Uno wrote:
....

> The topics I could cover well are
> 1) How to use gfortran on windows
> 2) How to use gfortran off a memory stick
....

If anything, I'd say those topics probably belong in their own
documentation as addenda perhaps for subsets of the overall gfortran
user base, not in the gfortran doc's themselves.

--
From: steve on
On Aug 1, 9:50 am, Uno <merrilljen...(a)q.com> wrote:
>
> I also consider it a distinct possibility that Jerry Delisle, Tobias
> Burnus, mathematican steve etc. don't want me fouling up gfortran.pdf
> with my puerile pictures.  I am becoming quite adept with GIMP, and can
> make a clean .jpg image of a size appropriate for the pdf format that is
> less a 100 k.
>

Actually, I'm a physicist with a mathematical bent.

> The topics I could cover well are
> 1)  How to use gfortran on windows
> 2)  How to use gfortran off a memory stick

IMHO, these topics would be better suited to the gfortran
wiki.

--
steve