Re: Hints for http://lilypond.org/doc/v2.13/Documentation/alternate-input

[Graham Percival]

On Sat, Nov 21, 2009 at 01:39:06AM +0100, Christian Herzberg wrote:
> Am Freitag, 20. November 2009 02:33:31 schrieb Graham Percival:
> > Other than that, it looks great.  Committed, and will appear
> > whenever 2.13.8 is out.
> 
> So here the next small changes:

Thanks, added!

Please note that this file is now in the directory
  Documentation/web/introduction.itely
Other than the general->web alteration, nothing has changed about
the way to work on this file.  :)

>  * Screenshot for LilyKDE (the pngs are included in this mail)
>    - This go to "[lilypond.git]/Documentation/pictures/"
>    - The png would collide with the help message.
>       The text will float, but the background will collide.

I don't quite follow... I suspect that there's a CSS problem,
which is unfortunate since I'm not really familiar with CSS.

>    - added names for links

I'm fine with this, but make sure that we have a link for which
the displayed name is the same as the link -- this is important in
case somebody prints the PDF; the paper version obviously won't
have a clickable url.  :)

(I'm not certain if you realized that the .itexi file you edit is
processed into HTML, PDF, and info formats)

>  * What means the "@"  in some content of @uref?

In texinfo, @ means "this is a command".  If you write
  uref{blahblah}
then it will be interpreted (and printed) as literal text; if you
write:
  @uref{blah,blah}
then texinfo knows that you want to make a "universal reference".


>  * the itemitze about apps exporting LilyPond
>    - reorder to have all non-graphical tools together

Ok.  We're now getting to more interesting questions -- how should
we present this information?

The top part of the page is somewhat in "most recommended" format.
People will begin reading from the top, so the best way to make
sure people notice something is to put it at the top.
Unfortunately, we can't put *everything* at the top, so we need to
make choices.

My thought is that Frescobaldi should get its own box (just like
lilypondtool), and be moved between lilypondtool and emacs/vim.
But I'm content to leave these judgements up to you -- you're a
very good and careful contributor, so I'm sure that you'll make
good decisions.

>  * screenshots for MuseScore, Canorus, Tuxguitar,
>     Rosegarden, Noteedit
>    - This will lead to a bad alignment between text and
>       screenshot. How should this be done?

This is a CSS issue, so I'm not quite certain, sorry.  :(

> Some suggestion beyond, I would like to discuss:
>  * Would you like to see all apps including
>     informations about there exporting and
>     importing formats?
>  * Would you like to differ the lily-exporting
>     apps in graphical and command line tools?

Hmm.  I definitely think we should indicate graphical /
command-line tools, but I'm not certain what the best way to do
that is.  Maybe something like:
  box: denemo
  box: lilypondtool
  box: frescobaldi
  box: emacs/vim
  box: all other graphical tools
  box: all other command-line tools
?
I'm only making a suggestion here -- as far as I'm concerned, you
have the final say on this matter.


As for the export/include formats... hmm.  My initial vote would
be "no", but maybe it's worth it.  My concern (as always) is the
length / amount of information.  From years of writing
documentation, I know that the more info you present, the less
people read.

The general idea of this page is to present a quick overview of
each editor, so that somebody can decide which one to try without
having to try all of them.  We need to make guesses about the
length of text description, size of screenshot (or whether to
include a screenshot at all!), and lists of operating systems,
graphical/text tool symbols, etc.

I'm happy to discuss these issues, but I want to make sure that
you know that you make the final decision.  If you disagree with
me, that's fine -- you're in charge of this page, so do whatever
you think is best.  :)

>  * Using the icons/symbols for each alternate
>     input application to help the recognition?

I like this idea!  Unfortunately, unless you are an artist, it
might take a bit more work than you realize -- we need to make
sure we use copyright-permissive icons.  If you find some symbols
published under the Creative Commons, that would be good.

Cheers,
- Graham