Re: New LilyPond website

[Carl Sorensen]

On 11/30/16 6:53 PM, "Paul" <address@hidden> wrote:

>On 11/30/2016 08:01 PM, John Roper wrote:
>
>> Why is the website auto generated? What content is auto generated or
>> is it just setup that way so that it is always built to the latest
>> version for releases?

By having the website auto generated, we never need to change the website
when we have a new release.  We only need to change the website when we
specifically want to change something about the website.  This
dramatically minimizes the amount of time spent on maintaining the website.

>
>Others can probably give better answers, as this is kind of second hand
>based on past discussions... but the website is basically an appendage
>to the (much larger) documentation, and, well let me quote
>
>https://www.gnu.org/software/texinfo/
>
>-------------------
>Texinfo is the official documentation format of the GNU project. It was
>invented by Richard Stallman and Bob Chassell many years ago, loosely
>based on Brian Reid's Scribe and other formatting languages of the time.
>It is used by many non-GNU projects as well.
>
>Texinfo uses a single source file to produce output in a number of
>formats, both online and printed (dvi, html, info, pdf, xml, etc.). This
>means that instead of writing different documents for online information
>and another for a printed manual, you need write only one document. And
>when the work is revised, you need revise only that one document. The
>Texinfo system is well-integrated with GNU Emacs.
>-------------------

One thing that is note mentioned in your quote is that texinfo separates
semantics from appearance.  It is this precise separation that allows one
to make big but consistent changes in the appearance of the website with
changes in the CSS.  I'm a firm believer in the principle of separating
semantics from presentation (and we do that with LilyPond, by the way,
which is one of its strengths IMO).

>
>So using texinfo to produce the documentation in info, pdf, html formats
>etc. is then also used for the website.  I think that's the main reason,
>but it's also tied up with supporting multiple translations of the
>docs/website and how building the docs runs LilyPond to generate all of
>the images for the examples, etc.  Also the argument is that having one
>system for docs and website is simpler and makes maintenance easier,
>especially with fewer contributors, etc.  That's the gist of past
>discussions.
>
>I think there's a case for decoupling the website from the documentation
>to a greater degree, e.g. as Federico argued earlier in the thread, but
>based on past discussions I am not optimistic that this would go as far
>as not using texinfo.  (But I've often wondered how important is it for
>the content of the website to be available in pdf and info formats.)

I don't think that there is any need for the website to be available in
pdf and info.  But IMO there is a huge need for the website to
presentation to be auto-generated from a semantic text description.  I
don't care how beautiful the new website is, if it requires a webmaster to
continually update the pages (including in all of the languages we have),
it's not a step forward.  It would be setting up the website for bitrot.

>
>Upgrading to the latest version of texi2any[0] and/or using Haunt would
>help, but those are non-trivial endeavors.  The current setup certainly
>introduces friction for website work, especially for those who are used
>to working directly with HTML.

I believe that we want to avoid working directly with HTML because of its
mixture of semantics and presentation.

Thanks,

Carl