From: Tobias Burnus on
Uno wrote:
> Janus Weil wrote:
>>> 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 I agree that the layout could be nicer, I fail to see why one
wants to see screen shots for Fortran (the language) or the compiler
(which is based on command line processing). Also all my Fortran books
do not have figures (except for things like flow charts).

[But see below.]

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

That's true on one hand; the other is that the users rather push for new
features and bug fixes and less for an improved documentation.
Especially, as there are great Fortran books.


>> 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.
>
> 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.

Well, the gfortran mailing lists serves two needs: Communication between
developers and for user support (cf. also gcc-help@).

> For example, I
> still don't know what a trunk is. I'm inclined to believe that it is to
> evoke the tree metaphor.

The name goes back to revision control systems, cf.
http://en.wikipedia.org/wiki/Revision_control

The main source code is on the trunk, where all the development happens
(currently: "4.6.0 (experimental)"). After about 8 months there is
stabilization phase ("stage 3") and after the number of regressions is
low enough, a branch is created (e.g. "4.5.x" with the first version
4.5.0). On the "trunk" one then can start adding new major features
while smaller fixes (especially for regressions) go into the branch
(leading minor stable version such as 4.5.1, 4.5.2, ...).


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

I think for (1) it depends on the what is covered, but I think part of
(1) and (2) do not really fit for gfortran.pdf. However, I regard them
as useful and worth to be documented.

For documentation, one needs to distinguish between the official GCC
documentation, which is available at http://gcc.gnu.org/onlinedocs/ -
and additional documentation.

The documentation at http://gcc.gnu.org/onlinedocs/ is maintained in the
texinfo format (http://www.gnu.org/software/texinfo/), has a copyright
asssignment to the Free Software Foundation (FSF), and is under the GNU
Free Documentation License. If one starts adding figures, one might need
to cross check with the GCC steering committee whether that's OK - it
probably is.

Additional documention, which can, e.g., be made available via the GCC
wiki: Here, anything goes.

For the official documentation, I can imagine more example, a more
extensive coverage of the Fortran language etc. If you want to
contribute to this part (beyond really trivial changes), you need a
copyright assignment with the FSF as outlined at
http://gcc.gnu.org/contribute.html

For a documentation how to run gfortran off a memory stick, how to use
it on Windows, in Eclipse etc., I think one should better create a
separate document - either as wiki page (http://gcc.gnu.org/wiki/) or as
separately distributed document - which can be linked, e.g., from the
wiki. Best would be still a FSF assignment as one could then turn it
into a normal FSF documentation, if needed.

(For the FSF and thus for GCC there exists only the source code - all
binary versions are the business of some "vendors" and not of GCC; in
practise there are strong links between Linux distributors, the Cygwin
and MinGW/MinGW64 project, and the provides of binaries at
http://gcc.gnu.org/wiki/GFortranBinaries - but officially all those do
not have anything to do with the FSF GCC version.)

Tobias
From: Uno on
nmm1(a)cam.ac.uk wrote:
> 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.

It has other defects, and isn't good for beginners, in particular those
who aren't used to having to antecedently know shift-q before you can
get the goddam thing from having pirated your terminal.

At least it understands ^C.
>
>> 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.

It's been one generation since I learned it, and I've knocked the rust
off of it thanks to usenet. So, given that I need to buy curtains
before I buy fortran software, I stay with gfortran and g95.

(I hope Andi's doing alright. It's hot as fricking Hades in the US SW
right now. Thank god I'm a mile high.)
--
Uno
From: Uno on
dpb wrote:
> 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.

What is the gfortran user base?
--
Uno
From: Uno on
steve wrote:
> 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.

I'd be curious to know more about your research area. One of my
favorite sequences in school was Mathematical Methods in the Physical
Sciences (got A's too, and a delta gamma to come and take notes for me
one day). We used the Nancy Boas text, which I've been known to dig up
at my local library serially.
>
>> 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.

How does that work?
--
Uno
From: steve on
On Aug 1, 12:51 pm, Uno <merrilljen...(a)q.com> wrote:
> steve wrote:
>>> 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
>
>> IMHO, these topics would be better suited to the gfortran
>> wiki.
>
> How does that work?

Anyone can edit the gfortran wiki. You don't need a copyright
assignment. Simply go to

http://gcc.gnu.org/wiki/GFortran

--
steve