Re: why is the wiki page on building octave so lacking?

[Richard Crozier]

On 16/03/2012 14:54, John W. Eaton wrote:
> On 16-Mar-2012, Richard Crozier wrote:
> 
> | I find the multi-page html output from this to be a poor
> | format, as it is impossible to get an overview of a topic.
> 
> Can you explain what you mean by that?  What changes to the generated
> HTML would improve the situation for you?  It is possible to generate
> the HTML output as a single page.  We currently don't have that on the
> web page, but we could easily add it.  If the style of the output is
> bad, then please suggest changes to the CSS file that is used for the
> the manual on the web site.  If you think there need to be more class
> or id tags in the generated HTML, then please bring up those issues
> with the Texinfo maintainers.
> 
> jwe
> 


The build instructions are split into too many pages in the html docs,
with only small amounts of information on each. To me this disrupts the
'flow' of the document. As an example, I would suggest consolidating G.1
Build Dependencies into a single page, and reconsidering how 'Tips for
Specific Systems' relates to this info.

On the page main 'Appendix G Installing Octave' I would consider adding
a little introduction outlining the steps used to build Octave before
launching straight into the links to specific sections. This would just
say something about how Octave uses the GNU makefile system, Ideally
this would have links to elsewhere that explain what 'make' and so on
are for real newbies, i.e. go to http://www.gnu.org/software/make/. The
intro could then state that before you can do this you will probably
need to obtain some other packages that Octave depends on, which then
leads onto the first link. It would also be useful to mention that
building is easiest on Unix-like systems and that building on other
systems may be more complex. You could also mention there are more
instructions in the readme files which come with the sources.

On the tips for specific systems page, I would not launch straight into

"The names of pre-compiled packages vary by system and do not always
match exactly the names listed above."

(they're actually listed below, or rather up and then down again on
another page).

Perhaps instead say something like:

"On some systems you can obtain many of Octave's build dependencies
automatically. The commands for doing this vary by system. Similarly,
the names of pre-compiled packages vary by system and do not always
match exactly the names listed in <Build Tools> and <External Packages>."

I would also rename this link to 'Obtaining the Dependencies
Automatically', as actually, this is what the page is about, you just
can't do it on all systems.

Another thing I would suggest is restricting the width of a page of
text. Around 66 characters per line is what most books (and latex) uses
as this has been found to be most readable. This is also the reason
scientific papers are double-column format, and newspapers use multiple
columns.

I would say, that now I've been through the pages a few times, all the
necessary info to build OCtave is present, it just doesn't follow a
narrative that tells the story of how to build Octave. Maybe it's just
me who thinks this though.

Richard

-- 
The University of Edinburgh is a charitable body, registered in
Scotland, with registration number SC005336.