GDP: length/page-splitting of subsections

classic Classic list List threaded Threaded
18 messages Options
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-user mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-user
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-user mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-user
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-user mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-user
Reply | Threaded
Open this post in threaded view
|

Re: GDP: length/page-splitting of subsections

Eyolf Østrem
In reply to this post by Kieren MacMillan
On 10.09.2007 (11:09), Kieren MacMillan wrote:
> Hi Graham (et al.):

> >Does anybody _like_ the current layout?


> That being said...  ;-)

> >My preference is for 2

> Me 2.

Me 3.

--
paak, n: A stadium or inclosed playing field. To put or leave (a
                        a vehicle) for a time in a certain location.
patato, n: The starchy, edible tuber of a widely cultivated plant.
Septemba, n: The 9th month of the year.
shua, n: Having no doubt; certain.
sista, n: A female having the same mother and father as the speaker.
tamato, n: A fleshy, smooth-skinned reddish fruit eaten in salads
                        or as a vegetable.
troopa, n: A state policeman.
Wista, n: A city in central Masschewsetts.
yaad, n: A tract of ground adjacent to a building.
                -- Massachewsetts Unabridged Dictionary


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

Re: GDP: length/page-splitting of subsections

fiëé visuëlle
In reply to this post by Graham Percival-2
Am 2007-09-10 um 17:00 schrieb Graham Percival:

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

No. I always use the online manual in several tabs (the fewer single  
pages, the fewer tabs!) and a Google tab with "site:lilypond.org/
doc/...", because it also finds the commands in samples (in contrary  
to the PDF), and often I only need a working sample of usage (the in-
text samples are often too short or not on topic as I understand it  
or too cluttered - or too simple).

BTW I'd like to see an forever-working URL like http://lilypond.org/ 
doc/current/Documentation/ (instead of the version; should need only  
one symlink; maybe "current-stable" and "current-dev").

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

If you rework the docs anyway, then 2 is good. Otherwise I'd prefer 1.


Greetlings from Lake Constance
---
fiëé visuëlle
Henning Hraban Ramm
http://www.fiee.net
http://angerweit.tikon.ch/lieder/
https://www.cacert.org (I'm an assurer)




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

Re: GDP: length/page-splitting of subsections

v.villenave
2007/9/10, fiëé visuëlle <[hidden email]>:

> No. I always use the online manual in several tabs (the fewer single
> pages, the fewer tabs!) and a Google tab with "site:lilypond.org/
> doc/...", because it also finds the commands in samples (in contrary
> to the PDF), and often I only need a working sample of usage (the in-
> text samples are often too short or not on topic as I understand it
> or too cluttered - or too simple).

This demonstrates what I said about people not using the LSR manual
search tool :)

Fiëé: you might be interested in opening
http://lsr.dsi.unimi.it/LSR/Manual in your google-tab. (or you might
not :)

> BTW I'd like to see an forever-working URL like http://lilypond.org/
> doc/current/Documentation/ (instead of the version; should need only
> one symlink; maybe "current-stable" and "current-dev").

Oh yes! Veeery good point!

Rune: I think it's possible with some JScript tweaking (at least, some
buzzword-compliant technologies allow to do this without frames). But
you're right, 1993-1994 were fun too :)

Valentin


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

Re: GDP: length/page-splitting of subsections

Rune Zedeler
Citat Valentin Villenave <[hidden email]>:

> Rune: I think it's possible with some JScript tweaking (at least, some
> buzzword-compliant technologies allow to do this without frames).

Maybe. I have just never seen it.
Javadoc still uses frames, and about everything else I have encountered reloads
the entire toc whenever you select a new entry in the toc.



_______________________________________________
lilypond-user mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-user
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-user mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-user
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-user mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-user
Reply | Threaded
Open this post in threaded view
|

Re: GDP: length/page-splitting of subsections

Graham Percival-2
In reply to this post by fiëé visuëlle
fiëé visuëlle wrote:
>
> samples (in contrary to the PDF), and often I only need a working sample
> of usage (the in-text samples are often too short or not on topic as I
> understand it or too cluttered - or too simple).

Hmm.  Samples are too sort, too cluttered, or too simple.  That will be
hard to fix.  :)

> BTW I'd like to see an forever-working URL like
> http://lilypond.org/doc/current/Documentation/ (instead of the version;
> should need only one symlink; maybe "current-stable" and "current-dev").

Well,
http://lilypond.org/doc/v2.11/Documentation/
gives you the current-dev.  Yes, you need to update this link whenever
we release a new stable branch... but that only happens once or twice a
  year.

>> 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.
>
> If you rework the docs anyway, then 2 is good. Otherwise I'd prefer 1.

We're reworking the docs now.  :)   ok, one more vote for 2.

Cheers,
- Graham


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

Re: GDP: length/page-splitting of subsections

Eyolf Østrem
> >BTW I'd like to see an forever-working URL like
> >http://lilypond.org/doc/current/Documentation/ (instead of the version;
> >should need only one symlink; maybe "current-stable" and "current-dev").

> Well,
> http://lilypond.org/doc/v2.11/Documentation/
> gives you the current-dev.  Yes, you need to update this link whenever we
> release a new stable branch... but that only happens once or twice a  
> year.

But what the OP said, is true, and a very simple thing to do, and it
means nobody will have to change their links as often as twice a year
:-)

e


--
love, n.:
        When, if asked to choose between your lover
        and happiness, you'd skip happiness in a heartbeat.


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

Re: GDP: length/page-splitting of subsections

fiëé visuëlle
In reply to this post by Graham Percival-2
Am 2007-09-10 um 20:45 schrieb Graham Percival:

> fiëé visuëlle wrote:
>> samples (in contrary to the PDF), and often I only need a working  
>> sample of usage (the in-text samples are often too short or not on  
>> topic as I understand it or too cluttered - or too simple).
> Hmm.  Samples are too sort, too cluttered, or too simple.  That  
> will be hard to fix.  :)

I know. Sorry for being no help here. And I didn't mean to blame you  
or anyone.
It's only that I often enough couldn't find a sample or an  
explanation (that I could understand) for my problems.
(I use LilyPond nearly exclusively for folk songs and choir settings...)

I'm very glad that you take on this big task (I know that coding is  
more fun than finding bugs and typos, being a developer and  
typesetter myself). I'd like to help, but simply am swamped with  
other projects.

Enough OT. EOT.

Greetlings from Lake Constance
---
fiëé visuëlle
Henning Hraban Ramm
http://www.fiee.net
http://angerweit.tikon.ch/lieder/
https://www.cacert.org (I'm an assurer)




_______________________________________________
lilypond-user mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-user
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
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

I know we're now drifting away from the goal of restructuring the
documentation into sections. Instead, this thread seems to be turning into
improving the general documentation system, which I regard as a step that
should be done before going into details of restructuring the actual manual.

- From the mails so far, I think it makes sense to have:
- -) Introductury tutorial covering the basics of Lilypond. The full docs need
to assume that the reader is aware of these. The current tutorial is too
basic to help in this regard.
- -) Extensive documentation (basically what we have now, after the
restructuring)
- -) LSR as an official part on the lilypond page, linked from the doc. The
regression testing page and the tips pages are a useful piece of resources,
but with hundreds of examples are simply not usable when you look for
something specific. LSR should (and is intended to, anyay) take over that
job.

As a personal comment: The documentation of lilypond is really great!!! It's
just that due to the load of small pages, it's easy to get lost and hard to
find a page again when you can't remember exactly.

Am Montag, 10. September 2007 schrieb Rune Zedeler:
> 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 :-)

Konqueror even has that nice feature to save a web page locally (in a .war
file, which ist just a zip file) including all images from that page... It
just takes a while for the browser to format a 5MB web page correctly, laying
out all images as they load...


Am Montag, 10. September 2007 schrieb fiëé visuëlle:
> BTW I'd like to see an forever-working URL like http://lilypond.org/
> doc/current/Documentation/ (instead of the version; should need only
> one symlink; maybe "current-stable" and "current-dev").

Fully agree with that!

Another suggestion: set up lsr.lilypond.org to point to the LSR (it might
still be located on the current .it server, but honestly who remembers that
URL???). That would also make the LSR appear as an official part of lilypond
instead of a third-party service.


Am Montag, 10. September 2007 schrieb Rune Zedeler:
> 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.

But you can't easily bookmark...

Cheers,
Reinhold
- --
- ------------------------------------------------------------------
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/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)

iD8DBQFG5a4/TqjEwhXvPN0RAvS5AJ9O/ZOKoOokkzC4AHr0Ik/ENw12ywCfSM0a
L+YSFbu8KZNnzToqvW1hISI=
=3WR+
-----END PGP SIGNATURE-----


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

Re: GDP: structure of index

John Mandereau-2
In reply to this post by Graham Percival-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-user mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-user
Reply | Threaded
Open this post in threaded view
|

Re: GDP: length/page-splitting of subsections

John Mandereau-2
In reply to this post by Eyolf Østrem
Le lundi 10 septembre 2007 à 20:49 +0200, Eyolf Østrem a écrit :

> > >BTW I'd like to see an forever-working URL like
> > >http://lilypond.org/doc/current/Documentation/ (instead of the version;
> > >should need only one symlink; maybe "current-stable" and "current-dev").
>
> > Well,
> > http://lilypond.org/doc/v2.11/Documentation/
> > gives you the current-dev.  Yes, you need to update this link whenever we
> > release a new stable branch... but that only happens once or twice a  
> > year.
>
> But what the OP said, is true, and a very simple thing to do, and it
> means nobody will have to change their links as often as twice a year
> :-)

That's wrong, the webmaster will have to change the symlinks :-P

Such symlinks already exist, but were only known by the webmasters and
the translators.

Have a look at this updated page to know about those permanent links:
http://lilypond.org/web/documentation
(Wait for one hour or two for the automatic regeneration of lilypond.org
from the web sources.)

Cheers,
John



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

Re: GDP: structure of index

Werner LEMBERG
In reply to this post by John Mandereau-2
> > > 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-user mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-user
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-user mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-user
Reply | Threaded
Open this post in threaded view
|

Re: GDP: length/page-splitting of subsections

fiëé visuëlle
In reply to this post by John Mandereau-2
Am 2007-09-11 um 01:13 schrieb John Mandereau:

> Such symlinks already exist, but were only known by the webmasters and
> the translators.
>
> Have a look at this updated page to know about those permanent links:
> http://lilypond.org/web/documentation
> (Wait for one hour or two for the automatic regeneration of  
> lilypond.org
> from the web sources.)

Thank you!

Greetlings from Lake Constance
---
fiëé visuëlle
Henning Hraban Ramm
http://www.fiee.net
http://angerweit.tikon.ch/lieder/
https://www.cacert.org (I'm an assurer)




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