GDP: length/page-splitting of subsections

classic Classic list List threaded Threaded
21 messages Options
12
Reply | Threaded
Open this post in threaded view
|

GDP: length/page-splitting of subsections

Graham Percival-2
To summarize some discussions:
- there seems to be considerable dislike for the current
"one-short-subsection-per-HTML-page" layout of the manual.  That
surprises me, since I've never had a problem with it, but of course I'm
intimately familiar with the layout of the manual, so I'm happy to
disregard my own opinion in this matter.

- Does anybody _like_ the current layout?  If so, speak up now or
forever hold your peace.  :)


There are two solutions for this:
1)  Don't split HTML by into subsections; have one html page per section.

2)  Merge many subsections.  For example,
6.1 Pitches
6.1.1 Writing pitches    (includes 6.1.1, 6.1.2, 6.1.3, 6.1.4, and 6.1.5
in the latest proposal)
6.1.2 Octaves/jumping pitches   (includes 6.1.6, 6.1.7, and 7.1.8)
6.1.3 Rests    (includes 6.1.9 and 6.10)

the names obviously need work.


My preference is for 2 -- I can't believe that users want to see
articulations, dynamics, and trills on the same HTML page.  But as I
said, we should probably disregard my opinion on this issue.

Thoughts?
- Graham


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: GDP: length/page-splitting of subsections

Kieren MacMillan
Hi Graham (et al.):

> Does anybody _like_ the current layout?

In some ways, my opinion won't matter, because I don't use (nor do I  
really understand why anyone else uses) the HTML manual -- the PDF  
documentation is all I ever use because:
     1. It's perfect for printing;
     2. Full-text searching is better, faster, and more convenient;
     3. It doesn't require me to be on-line to access it (nor to have/
build a local copy of the HTML docs).

That being said...  ;-)

> My preference is for 2

Me 2.

Best regards,
Kieren.


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: GDP: length/page-splitting of subsections

John Mandereau-2
In reply to this post by Graham Percival-2
Le lundi 10 septembre 2007 à 08:00 -0700, Graham Percival a écrit :

> To summarize some discussions:
> - there seems to be considerable dislike for the current
> "one-short-subsection-per-HTML-page" layout of the manual.  That
> surprises me, since I've never had a problem with it, but of course I'm
> intimately familiar with the layout of the manual, so I'm happy to
> disregard my own opinion in this matter.
>
> - Does anybody _like_ the current layout?  If so, speak up now or
> forever hold your peace.  :)
>
>
> There are two solutions for this:
> 1)  Don't split HTML by into subsections; have one html page per section.
>
> 2)  Merge many subsections.  For example,
> 6.1 Pitches
> 6.1.1 Writing pitches    (includes 6.1.1, 6.1.2, 6.1.3, 6.1.4, and 6.1.5
> in the latest proposal)
> 6.1.2 Octaves/jumping pitches   (includes 6.1.6, 6.1.7, and 7.1.8)
> 6.1.3 Rests    (includes 6.1.9 and 6.10)
>
> the names obviously need work.
>
>
> My preference is for 2 -- I can't believe that users want to see
> articulations, dynamics, and trills on the same HTML page.  But as I
> said, we should probably disregard my opinion on this issue.


I vote for option 2 too, as it's a better compromise between easier full
text search and load time when reading docs online.

John



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: GDP: length/page-splitting of subsections

Reinhold Kainhofer
In reply to this post by Graham Percival-2
Am Montag, 10. September 2007 schrieb Graham Percival:
> My preference is for 2 -- I can't believe that users want to see
> articulations, dynamics, and trills on the same HTML page. .

Why not? They are all ornaments to a note. In particular, if you are not a
professional musician, the distinction e.g. between articulations and trills
is not so clear.



--
------------------------------------------------------------------
Reinhold Kainhofer, Vienna University of Technology, Austria
email: [hidden email], http://reinhold.kainhofer.com/
 * Financial and Actuarial Mathematics, TU Wien, http://www.fam.tuwien.ac.at/
 * K Desktop Environment, http://www.kde.org, KOrganizer maintainer
 * Chorvereinigung "Jung-Wien", http://www.jung-wien.at/


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: GDP: length/page-splitting of subsections

Kieren MacMillan
Hi Reinhold,

> They are all ornaments to a note.

Articulations and trills, I buy.

Dynamics are different, IMO.
At the very least, there are more (and more complex) things you can  
do with dynamics (in Lilypond), and so that section alone would be  
long enough to deserve its own HTML page.

Regards,
Kieren.


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: GDP: length/page-splitting of subsections

Graham Percival-2
Kieren MacMillan wrote:
> Hi Reinhold,
>
>> They are all ornaments to a note.
>
> At the very least, there are more (and more complex) things you can do
> with dynamics (in Lilypond), and so that section alone would be long
> enough to deserve its own HTML page.

I'd certainly say so... but there's a large element of "the customer is
always right" here.

The all-in-one HTML page is **5 megs**.  I'm astounded that so many
people (ie more than 0) are choosing to download that monster _every
time_ they want to look something up in the docs.  That's a terrible
waste of bandwidth, especially if you consider that the answer they're
looking for is probably 1k of text and 100k of example picture.  To me,
that sounds like a terrible indictment of how badly organized the docs are.


Let me phrase this question differently:
- if you currently use the all-in-one HTML page, how could we organize
the non-all-in-one docs such that you use them?

Remember that you can search the docs online as part of LSR.

Cheers,
- Graham


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: GDP: length/page-splitting of subsections

v.villenave
2007/9/10, Graham Percival <[hidden email]>:

> I'd certainly say so... but there's a large element of "the customer is
> always right" here.
>
> The all-in-one HTML page is **5 megs**.  I'm astounded that so many
> people (ie more than 0) are choosing to download that monster _every
> time_ they want to look something up in the docs.  That's a terrible
> waste of bandwidth, especially if you consider that the answer they're
> looking for is probably 1k of text and 100k of example picture.  To me,
> that sounds like a terrible indictment of how badly organized the docs are.

...Or how badly we need an integrated search tool.

> Let me phrase this question differently:
> - if you currently use the all-in-one HTML page, how could we organize
> the non-all-in-one docs such that you use them?

I'm absolutely fine with the one-tiny-subsection-per-page.
*I* like the current layout.

> Remember that you can search the docs online as part of LSR.

Yes, but I think this should definitely be implemented on lilypond.org itself.

Regards,
Valentin


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: GDP: length/page-splitting of subsections

Kieren MacMillan
In reply to this post by Graham Percival-2
Hi Graham,

> - if you currently use the all-in-one HTML page, how could we  
> organize the non-all-in-one docs such that you use them?

Again, I don't, but OTTOMH...

If the doc index ran along the left-hand side of the page (e.g., in a  
frame, via CSS menus, etc.), might that help people who use the  
monster? I know it helps me when I'm using Java class documentation.

Cheers,
Kieren.


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: GDP: length/page-splitting of subsections

v.villenave
2007/9/10, Kieren MacMillan <[hidden email]>:

> If the doc index ran along the left-hand side of the page (e.g., in a
> frame, via CSS menus, etc.), might that help people who use the
> monster? I know it helps me when I'm using Java class documentation.

I agree!
I thought I was the only CSS-addict guy here :)
I think CSS allows to do this without needing an extra (ugly) frame.
Plus, I always wish the site and the docs could look a bit fancier...

Valentin


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: GDP: length/page-splitting of subsections

Kieren MacMillan
Hi Valentin,

> I think CSS allows to do this without needing an extra (ugly) frame.

Agreed -- of the many possible options, I definitely prefer valid  
XHTML+CSS.

> Plus, I always wish the site and the docs could look a bit fancier...

=)

Best,
Kieren.


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: GDP: length/page-splitting of subsections

Rune Zedeler
In reply to this post by Graham Percival-2
Citat Graham Percival <[hidden email]>:

> The all-in-one HTML page is **5 megs**.  I'm astounded that so many
> people (ie more than 0) are choosing to download that monster _every
> time_ they want to look something up in the docs.

We don't.
Browsers have caches, you know :-)

> Let me phrase this question differently:
> - if you currently use the all-in-one HTML page, how could we organize
> the non-all-in-one docs such that you use them?

I actually think that if we have each section on one full page (suggestion 1,
that is) I would start using the several pages manual.
Navigating so much as what is nessesary in the current manual I loose the
overview and spend too much time waiting for the page to load.
I agree that loading times are important. But for me, typically it is the
request time (i.e. the delay), not the transfer time (i.e. the speed) that is
the limit. I often have to wait several seconds from I press a link till it
starts to load. But as soon as it loads it goes very fast.
I did a very quick count, it seems like we have something like 60 sections.
If the whole manual is 5Mb, that means that each section is about 120kb.
On a 256kbps line (that is, on a rather slow line) loading the whole thing will
take four seconds. Add to that that you can start reading as soon as just the
text has been loaded - before the images are compoletet - I will say that the
"loading times" argument for possibility 2 is nonsense.
What takes time is requesting the page - not loading it after it has been
requested. Hence, the fewer pages to reqeust, the less loading time.




_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: GDP: length/page-splitting of subsections

Rune Zedeler
In reply to this post by v.villenave
Citat Valentin Villenave <[hidden email]>:

> I think CSS allows to do this without needing an extra (ugly) frame.

It is possible with css, but you would have to redownload the entire toc each
time.
With frames the toc stays and you only load the pages themself.
We were talking loading times :-)

-Rune (who likes frames)



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: GDP: length/page-splitting of subsections

Francisco Vila-3
El lun, 10-09-2007 a las 19:25 +0200, Rune Zedeler escribió:
> With frames the toc stays and you only load the pages themself.
> We were talking loading times :-)
>
> -Rune (who likes frames)
>

Please forget the idea of using frames, there are dozens of reasons for
not to use them, in my opinion. The worst being that framed pages are
not safely bookmarkable or linkable.
--
Francisco Vila. Badajoz (Spain)
http://www.paconet.org



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: GDP: length/page-splitting of subsections

Juergen Reuter
In reply to this post by Graham Percival-2
On Mon, 10 Sep 2007, Graham Percival wrote:

> To summarize some discussions:
> ...
>
> - Does anybody _like_ the current layout?  If so, speak up now or forever
> hold your peace.  :)
>

I am _fine_ with the current layout.  However, I agree that for
global searching in the web browser, you need a big html page, as has
already pointed out by various other people.  However, if you really _cry_
for global searching, this fact may indicate that the current index is
(for whatever reason) unsufficient.

Regarding the current index, I wonder why the items of the command index
also appear in the large index, thus making it unnecessarily long.  Lack
of consistency is IMHO another major problem (btw. there is a typo in the
index as of .32: "\displayLilyMusc" iso. "\displayLilyMusic").  Another
problem is that documentation writers often do not consider under which
terms a reader of the manual may try to look up a feature; often only the
most specific term is used; synonyms or categorizing terms are missing.
One example (which is most likely my own fault ;-)) is ancient notation:
if you are looking for "ancient" in alphabetical order, you will not find
anything in the index.  "Ancient" only occurs in composed terms such as
"rests, ancient" or as part of the associated section name.  At least in
the printed version (i.e. without CTRL-F search available) you are lost.
Similarly, you will find "killCues" only under "k" but not under "cues"
(i.e. if you do not know the exact name, it will be hard for you to find
it in the manual).

Furthermore, I would like to see entries like

   \displayLilyMusic: Displaying LilyPond notation
   \displayLilyMusic: Displaying music expressions

rather being structured as follows:

   \displayLilyMusic:
       Displaying LilyPond notation
       Displaying music expressions

Given the large size of the documentation, a single person probably can
not care for documentation-wide consistency of these (important!)
nitpicks.  Maybe a general good idea is to collect a couple of "do" and
"don't" examples as guideline for documentation writers?

Greetings,
Juergen


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: GDP: structure of index

Graham Percival-2
Juergen Reuter wrote:

> Furthermore, I would like to see entries like
>
>   \displayLilyMusic: Displaying LilyPond notation
>   \displayLilyMusic: Displaying music expressions
>
> rather being structured as follows:
>
>   \displayLilyMusic:
>       Displaying LilyPond notation
>       Displaying music expressions
>

I'm not certain if texinfo 4.8 can do that.  Werner, do you know?

If not, we could always make a feature request to the texinfo
developers; it might be possible for them to add it before 4.9.


> Given the large size of the documentation, a single person probably can
> not care for documentation-wide consistency of these (important!)
> nitpicks.  Maybe a general good idea is to collect a couple of "do" and
> "don't" examples as guideline for documentation writers?

Oh, totally.  README.txt is intended as that, and the main focus of GDP
is to fix all these consistency issues.  That's why I have 70 hours
budgeted for text-entry stuff (ie checking the .tely files) and only 40
for complicated stuff (like this rearrangement discussion)

Cheers,
- Graham


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: GDP: structure of index

John Mandereau-2
Le lundi 10 septembre 2007 à 11:06 -0700, Graham Percival a écrit :

> Juergen Reuter wrote:
> > Furthermore, I would like to see entries like
> >
> >   \displayLilyMusic: Displaying LilyPond notation
> >   \displayLilyMusic: Displaying music expressions
> >
> > rather being structured as follows:
> >
> >   \displayLilyMusic:
> >       Displaying LilyPond notation
> >       Displaying music expressions
> >
>
> I'm not certain if texinfo 4.8 can do that.  Werner, do you know?

I've just looked at Texinfo 4.8 manual (the latest release 4.9 only
differs about texi2dvi, texinfo.tex and some bugfixes), and found no way
to format an index as Juergen suggested.


> If not, we could always make a feature request to the texinfo
> developers;

It's already in Texinfo TODO file, which is quite big [1] -- Texinfo
needs a lot of C hackers to tackle all TODO items :-|  We can always try
to ask them to raise the priority for implementing this particular
feature.  (I'm suscribed to bug-texinfo, which discusses Texinfo bugs,
development and feature requests.)

[1] http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/TODO?rev=HEAD
See also http://www.gnu.org/software/texinfo/


>  it might be possible for them to add it before 4.9.

FWIW 4.9 was released on June 29, and the latest beta is 4.9.92, so they
might add it before 4.11... (or before 5.1 in case they decide to
release 5.0 instead of 4.10)

Cheers,
John



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: GDP: structure of index

Werner LEMBERG
> > > Furthermore, I would like to see entries like
> > >
> > >   \displayLilyMusic: Displaying LilyPond notation
> > >   \displayLilyMusic: Displaying music expressions
> > >
> > > rather being structured as follows:
> > >
> > >   \displayLilyMusic:
> > >       Displaying LilyPond notation
> > >       Displaying music expressions

If at all, it should be

  \displayLilyMusic: Displaying LilyPond notation,
    Displaying music expressions

otherwise it sticks out far too promimently.

> > I'm not certain if texinfo 4.8 can do that.  Werner, do you know?

No, sorry.

> FWIW 4.9 was released on June 29, and the latest beta is 4.9.92, so
> they might add it before 4.11...

4.11 has been released two days ago.


    Werner


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: GDP: length/page-splitting of subsections

Mats Bengtsson-4
In reply to this post by Graham Percival-2


Graham Percival wrote:

>
> There are two solutions for this:
> 1)  Don't split HTML by into subsections; have one html page per section.
>
> 2)  Merge many subsections.  For example,
> 6.1 Pitches
> 6.1.1 Writing pitches    (includes 6.1.1, 6.1.2, 6.1.3, 6.1.4, and
> 6.1.5 in the latest proposal)
> 6.1.2 Octaves/jumping pitches   (includes 6.1.6, 6.1.7, and 7.1.8)
> 6.1.3 Rests    (includes 6.1.9 and 6.10)
>
> the names obviously need work.
>
>
> My preference is for 2 -- I can't believe that users want to see
> articulations, dynamics, and trills on the same HTML page.  But as I
> said, we should probably disregard my opinion on this issue.
Yes, merging some selected subsections is probably the best solution.

    /Mats


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: GDP: length/page-splitting of subsections

Erik Sandberg-2
In reply to this post by Graham Percival-2
On Monday 10 September 2007, Graham Percival wrote:

> Kieren MacMillan wrote:
> > Hi Reinhold,
> >
> >> They are all ornaments to a note.
> >
> > At the very least, there are more (and more complex) things you can do
> > with dynamics (in Lilypond), and so that section alone would be long
> > enough to deserve its own HTML page.
>
> I'd certainly say so... but there's a large element of "the customer is
> always right" here.
>
> The all-in-one HTML page is **5 megs**.  I'm astounded that so many
> people (ie more than 0) are choosing to download that monster _every
> time_ they want to look something up in the docs.  That's a terrible
> waste of bandwidth, especially if you consider that the answer they're
> looking for is probably 1k of text and 100k of example picture.  To me,
> that sounds like a terrible indictment of how badly organized the docs are.
>
>
> Let me phrase this question differently:
> - if you currently use the all-in-one HTML page, how could we organize
> the non-all-in-one docs such that you use them?
>
> Remember that you can search the docs online as part of LSR.

What about creating a 'lilypond documentation search' plugin for Firefox
Search Bar? It could either use the LSR search, or google (using
site:http://lilypond.org/doc/v2.10/Documentation/). This would be a useful
application of the search bar, IMHO.

Erik


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: GDP: length/page-splitting of subsections

Han-Wen Nienhuys-3
In reply to this post by Graham Percival-2
2007/9/10, Graham Percival <[hidden email]>:

> > At the very least, there are more (and more complex) things you can do
> > with dynamics (in Lilypond), and so that section alone would be long
> > enough to deserve its own HTML page.
>
> I'd certainly say so... but there's a large element of "the customer is
> always right" here.
>
> The all-in-one HTML page is **5 megs**.  I'm astounded that so many
> people (ie more than 0) are choosing to download that monster _every
> time_ they want to look something up in the docs.  That's a terrible
> waste of bandwidth, especially if you consider that the answer they're
> looking for is probably 1k of text and 100k of example picture.  To me,
> that sounds like a terrible indictment of how badly organized the docs are.
>
>
> Let me phrase this question differently:
> - if you currently use the all-in-one HTML page, how could we organize
> the non-all-in-one docs such that you use them?

I haven't followed the discussion in detail, but isn't this something
that should be handled by makeinfo? It has a --split-size argument,
but that only works for info and plain text. If we could set size
limits to html files too, wouldn't that solve the problem?

--
Han-Wen Nienhuys - [hidden email] - http://www.xs4all.nl/~hanwen


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
12