CUTCODEDOWN
Minimalist Semantic Markup

Welcome Guest
Please Login or Register

If you have registered but not recieved your activation e-mail in a reasonable amount of time, please use our Contact Form for assistance. Include both your username and the e-mail you tried to register with.

Author Topic: LilyPond website  (Read 133 times)

karlinhigh

  • Newbie
  • *
  • Posts: 3
  • Karma: +0/-0
    • View Profile
LilyPond website
« on: 29 Feb 2020, 11:39:47 pm »
TL;DR: I want to make the website at lilypond.org look and work mostly like this one...

lilypondcss.s3-website-us-east-1.amazonaws.com/johnroper/build/index.html

...while only changing CSS and avoiding JavaScript and framework dependencies as far as possible. Does this look easy or hard? If you were hired to do this, what would you charge?

Long version: I am a volunteer doing some research and testing for the GNU LilyPond project. (lilypond.org, sheet music software) The project's website is due for a refresh as it currently lacks responsive design for mobile devices. However, the site's development environment is unique. Quoting the project's Contributor's Guide:

Quote
The website is not written directly in HTML; instead, it is autogenerated along with the documentation using Texinfo source files. Texinfo is the standard for documentation of GNU software and allows generating output in HTML, PDF, and Info formats, which drastically reduces maintenance effort and ensures that the website content is consistent with the rest of the documentation. This makes the environment for improving the website rather different from common web development.
lilypond.org/doc/v2.19/Documentation/contributor/introduction-to-website-work

Passing web developers have offered site redesigns. Usually, the offers involve switching the whole thing to a CMS of some sort. But that would separate website work from documentation work, and unless the person making that offer is prepared to "own" the website for the years to come, the project's developer community is unlikely interested in such large-scale changes.

Instead, they'd rather see a redesign based on changes to the CSS file, preferably with minimal JavaScript or framework dependencies. Also, the LilyPond software is plain-text centric and attractive to vision-impaired people using screen readers and such, which means that the website should be accessibility-compliant and play nice for those use cases. The project's entire web design philosophy seems not far from what's expressed on the CutCodeDown website. (Well, maybe except for the parts where "curmudgeon effect" gets dialed to "11," I jest. The most acerbic LilyPond people would probably stop at "9.")

Once, there was a redesign suggestion that came up with a look the developer community liked. It's visible here:
lilypondcss.s3-website-us-east-1.amazonaws.com/johnroper/build/index.html

That is just a proof-of-concept mock-up and is not based on the actual deployed HTML files, so specific criticism of it will likely be a wasted effort. There are 2 pages, the top-menu "home" (index.html) and "download" options. The rest of the links go to the current site. The mock-up is a mild refresh from the current look and adds responsive design.  That redesign effort stalled when it came down to rewriting it for the LilyPond project's preferred CSS-only web development environment, without using frameworks such as JQuery, Tether, or Bootstrap as found in the mock-up. Changing the site's HTML isn't impossible but should be considered expensive. Such changes could involve writing Texinfo that gets fed to texi2html running in a uniquely wonderful, hard-won configuration that's been serving the project untouched for the past decade or so.

I am not a web developer personally. I am aware of some foundational concepts of HTML and CSS but have effectively no project experience with them. I'm only exploring this because no one else has. I can try to puzzle all this out on my own, but it will probably take me 10 times as long and be less than half as good as what others on this forum could do; reading cutcodedown.com was both inspiring and confidence-destroying. The approach I'd use would involve analyzing the mock-up site with in-browser F12 developer tools, extracting properties for each element, and then trying to re-implement them in ways the LilyPond project expects, inspired by the methods CutCodeDown describes.

In closing, the LilyPond project is about to release a new version of its software and will probably draw extra traffic to its website. I'd like to see it updated to something like that mock-up design, but I'm not sure I'm capable. If someone else said "I already did it in my head just looking at it; for USD 100 or so the CSS file is yours" I'd probably just send the money. Any comments or condolences?

Jason Knight

  • Administrator
  • Sr. Member
  • *****
  • Posts: 303
  • Karma: +33/-1
    • View Profile
    • CutCodeDown -- Minimalist Semantic Markup
Re: LilyPond website
« Reply #1 on: 1 Mar 2020, 06:17:34 am »
I'd really have to see what it's back-ended by to weigh in on the proper course of action. It's HTML 4 transitional at some of its worst, which basically means it's ACTUALLY HTML 3.2, so the markup isn't just 22 years out of date, it's riddled with bugs and broken methodology that can cause accessibility woes.

Like the header menu being at the BOTTOM of the markup... or the <a name=""> stuff that went the way of the dodo 15 years ago as ID serves the same purpose. Or the misuse of numbered headings with all the H3 that there's no H2 for them to be children of. Even the use of <p>aragraph is overboard as it has <p> wrapping things that flat out just aren't paragraphs.

I mean just this alone:

Code: [Select]
<body lang="en" class="web devStatus">

<div id="main">
<a name="Top"></a>

<a name="top"></a>
<h1 class="settitle">LilyPond... music notation for everyone</h1>






<div id="pageHeader"><a name="LilyPond"></a>
<h2 class="heading">LilyPond</h2>

<p>... music notation for everyone
</p>
</div>
<div id="lilylogo">
  <img src="pictures/double-lily-modified3.png" alt="LilyPond logo">
</div>

Is indicative of HTML written by people who shouldn't have been doing so for a "serious" project. lang="en" should be on <html> not <body>, there's ZERO reason for the DIV around the img, that P should be part of the heading, there's no reason for two headings, <a name=""> isn't something we do anymore and is a waste of code doing id=""'s job, it's got TWO pointless name="top" anchors, and don't even get me started about the classes on H1 (without HTML 5's <section> no page should ever have more than one H1, so it never needs a class!) or on BODY (where 99% of the time the only thing that would/should be putting a class on BODY is scripting.)

That "rewrite" is equally flawed in that a lot of the links -- at least hovered or visited -- are of illegible colour contrasts. It's nice that it flattens things, ditches the serif fonts, etc, but it still has issues. (though many of those are bootcrap's fault)

Without seeing the back end code and how the site is being constructed from the texinfo, it's hard to say for sure. I mean, is it texiweb? Sphinx? Something in-house?

As to what I'd personally charge it would range from $150 all the way up to two grand depending on what needs to be done.

... but with that 20+ year out of date markup riddled with broken and outdated practices? Trying to "fix" things just using CSS isn't the answer. It can be done, but I HIGHLY recommend against it given a lot of the fundamental accessibility issues would remain unaddressed.

Problems that likely don't have much to do with the use of texinfo, and more to do with what's turning it into HTML. I'm not that familiar with texinfo other than the fact it was made by that dirtbag Stallman, much less the antiquated, deprecated, and no longer under development texi2html which is what appears to be making the pages.

Like most things Gnu/FSF it either thinks it's still 1970 and we're using mainframes, or it has its cranium wedged up 1997's backside. Aka the last time Stallman and his ilk were actually relevant.
« Last Edit: 1 Mar 2020, 06:24:29 am by Jason Knight »
"It is amazing what can be accomplished when nobody cares who gets the credit." -- Kelly Johnson

mmerlinn

  • Newbie
  • *
  • Posts: 26
  • Karma: +1/-0
  • Nutcake
    • View Profile
Re: LilyPond website
« Reply #2 on: 1 Mar 2020, 12:30:58 pm »

Quote
The website is not written directly in HTML; instead, it is autogenerated along with the documentation using Texinfo source files. Texinfo is the standard for documentation of GNU software and allows generating output in HTML, PDF, and Info formats, which drastically reduces maintenance effort and ensures that the website content is consistent with the rest of the documentation. This makes the environment for improving the website rather different from common web development.

Changing the site's HTML isn't impossible but should be considered expensive. Such changes could involve writing Texinfo that gets fed to texi2html running in a uniquely wonderful, hard-won configuration that's been serving the project untouched for the past decade or so.


It appears to me that you would rather keep using Texinfo & text2html.  However, that does not appear possible based on many things, in particular solving your accessibility issues.

Based on my SHORT gander at text2info, the only way to both use text2info AND solve your issues is a partial, or maybe complete, rewrite of text2info to address your concerns.

It appears to me that you have three choices:

1) Keep using text2html as is while ignoring accessibility and other issues
2) Rewrite text2html resolving all issues
3) Move to some other method of maintaining and updating your pages

Based on your needs, none of those choices are ideal.
The soul purr pus of a spell cheque cur is two valley date hour ignore ants.

karlinhigh

  • Newbie
  • *
  • Posts: 3
  • Karma: +0/-0
    • View Profile
Re: LilyPond website
« Reply #3 on: 4 Mar 2020, 05:14:23 pm »
Thank you for the responses. I've understood that the website needs more than just CSS fixes.

As far as I understand the back-end of this, it uses an old version of texi2html because the newer texi2any that replaced it lacks equivalent functionality in some ways. Here are links to Texinfo source files, if anyone's interested.

git.savannah.gnu.org/cgit/lilypond.git/tree/Documentation/web.texi
git.savannah.gnu.org/cgit/lilypond.git/tree/Documentation/web

But the config file that teaches texi2html how to generate the website is over 2,400 lines long, and I don't really expect any sane and skilled web developer to dig into it.

git.savannah.gnu.org/cgit/lilypond.git/tree/Documentation/lilypond-texi2html.init

I don't know that anyone in the Lilypond project pretends this situation is ideal. I also don't see any capacity for completely reimplementing the documentation (thousands of pages in 11 different translations) and its containing website in different infrastructure.

For now, I plan to keep exploring the situation, and I'll be back if and when I get improved HTML code to critique.

One thing: Texinfo says it has HTML 4 output.

www.gnu.org/software/texinfo/manual/texinfo/html_node/HTML-Translation.html

The CutCodeDown articles have lots of criticism for HTML 5. I supposed there's nothing inherently wrong with building on correctly-coded HTML 4?

mmerlinn

  • Newbie
  • *
  • Posts: 26
  • Karma: +1/-0
  • Nutcake
    • View Profile
Re: LilyPond website
« Reply #4 on: 4 Mar 2020, 09:46:15 pm »

The CutCodeDown articles have lots of criticism for HTML 5. I supposed there's nothing inherently wrong with building on correctly-coded HTML 4?

HTML 4, as far as I know, works in all modern browsers.  HTML 5, though, is not fully supported in browsers before the introduction of HTML 5.  So, the big question is, "What browsers are your clients using?" If they are mostly using older browsers, then moving to HTML 5 may cause a big drop in usage, mostly depending on whether you are using HTML tags unique to HTML 5.
The soul purr pus of a spell cheque cur is two valley date hour ignore ants.

Jason Knight

  • Administrator
  • Sr. Member
  • *****
  • Posts: 303
  • Karma: +33/-1
    • View Profile
    • CutCodeDown -- Minimalist Semantic Markup
Re: LilyPond website
« Reply #5 on: 5 Mar 2020, 02:17:59 am »
The CutCodeDown articles have lots of criticism for HTML 5. I supposed there's nothing inherently wrong with building on correctly-coded HTML 4?

One of the problems is that simply saying "HTML 4" is insufficient as there are TWO HTML 4's: Transitional and Strict.

Strict is the "real" HTML 4 implementing all the rules and good practices. Tranny on the other hand is just HTML 3.2 in drag, literally meaning "in transition from 1997 to 1998 practices".

... and since the first line of the site reads:

Code: [Select]
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">It's tucking back Mr. Winky, slapping on theatrical makeup,  and putting on the CFM boots for a night on the town... since apparently it's not just transitional, it's also loose.

Though much of that stems from their still using texthtml which as I mentioned is the old outdated and deprecated way of turning tex into markup. It's built into texinfo now and should be handled there.

See:
https://www.nongnu.org/texi2html/

The program has been dead for a decade now. Kind of like texinfo itself since I don't know many places that still use said relic of the early 1990's since, well... what are the odds they're actually going to print the documentation.

Structurally there is NOT significant difference between HTML and Tex, excepting that tex is the less accessible of the two in terms of code legibility... so I'm not sure just exactly what texinfo is giving them that HTML does not any time after around 2005. Admittedly I say the same thing about how people throw base64 at things, a relic of 1970's 6 bit computing!

But really if they are so set on texinfo for Christmas only knows what, to turn it into HTML texi2any is what should be used since it's still maintained and updated:

https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Generic-Translator-texi2any.html

Now, as to the file you linked to.. Perl... what is this 2003?

If this were brought to me by a paying client, I would be asking again just what it is that they think texinfo is giving them that HTML is not, particularly with the goofy and cryptic use of PERL with zero legitimate organization brings to the table. It's an outdated outmoded relic that does little if anything of value compared to HTML any time after 1998.

Because to be frank this cryptic mess without code indentation to make it clear which blocks are which:

Code: [Select]
@divId{pageHeader}
@heading LilyPond

... music notation for everyone
@divEnd

@c @imageId{cmws,web-clef-g-eight-alpha.png,Catchy Musical Web Snippet}
@imageId{lilylogo,double-lily-modified3,png,LilyPond logo}
@c @im ageId{cmws,web-snippet-alpha.png,Catchy Musical Web Snippet}

@divId{quickSummary}
LilyPond is a music engraving program, devoted to producing the
highest-quality sheet music possible.  It brings the aesthetics of
traditionally engraved music to computer printouts.  LilyPond is free
software and part of the @uref{https://gnu.org,GNU Project}.


@divClass{align-right}
Read more in our @ref{Introduction}!

@divEnd
@divEnd

is in no way, shape, or form easier to edit, develop, or deal with than:

Code: [Select]
<section id="LilyPond">
<img
src="pictures/double-lily-modified3.png"
alt="LilyPond logo"
>
<h2>
LilyPond<br>
<small>... music notation for everyone</small>
</h2>
<p>
LilyPond is a music engraving program, devoted to producing the highest-quality sheet music possible.  It brings the aesthetics of traditionally engraved music to computer printouts.  LilyPond is free software and part of the <a href="https://gnu.org">GNU Project</a>.
</p>
<div class="readMore">
Read more in our <a href="introduction.html">Introduction</a>!
<!-- .readMore --></div>
<!-- #LilyPond --></div>

Which is realistically all that needs to be written... and it's not like the media target attribute can't be used to target print specifically or any other media device. Hence why texinfo SHOULD have died off 10-15 years ago no matter how badly big iron dinosaurs with their derpy emacs editor want to stay relevant. Even with the full words to say what things ARE, it's STILL 50 bytes less code.

Convert it all to html, work on it in HTML, use a server-side language such as php to glue together like components of every page, and use CSS to convert it to each and every format desired like print (which also covers PDF), screen, aural, etc.

Unless they're using texinfo for something completely out of left field, which is actually highly unlikely. It's painfully cryptic, too easy to screw up in, and much like many other *nix fanboy BS was created at a time when keyboards still only had 52 to 64 keys, communications were at an unreliable 150 to 300 baud, systems only had 6 bit character spaces, and companies like DEC, WANG, and WYSE still had relevance.

In case you couldn't guess, I'm not exactly "GNU / FSF" friendly.

Really, what is it that texinfo and Perl is giving them that HTML + PHP can't, other than painfully cryptic hard to follow code?
"It is amazing what can be accomplished when nobody cares who gets the credit." -- Kelly Johnson

karlinhigh

  • Newbie
  • *
  • Posts: 3
  • Karma: +0/-0
    • View Profile
Re: LilyPond website
« Reply #6 on: 5 Mar 2020, 09:43:51 am »
Okay, thanks again. HTML 4 Strict sounds like the most likely way forward.

Jason Knight

  • Administrator
  • Sr. Member
  • *****
  • Posts: 303
  • Karma: +33/-1
    • View Profile
    • CutCodeDown -- Minimalist Semantic Markup
Re: LilyPond website
« Reply #7 on: 5 Mar 2020, 11:16:17 am »
Okay, thanks again. HTML 4 Strict sounds like the most likely way forward.
Well... no. Sadly 5 is the future and we have to get used to it, but remember, 5 is a SUPERSET of 4. As such you can write as 4 Strict and still deploy as HTML 5 for the handful of actual improvements.

There are a LOT of new things in 5 worth using. The new <input type=""> for example like "email" and "number", the pattern="" regex for <input>, tags like <time> and the reduced header size thanks to the new charset and language declaration methods. ALL well worth deploying HTML 5 for.

It's just that there are a bunch of new tags that don't serve a legitimate purpose and just result in either code bloat, or pointless redundancies.

ARTICLE, MAIN, NAV, SECTION, ASIDE, HEADER, and FOOTER are the tags you can just choose not to use, or to use sparingly in the handful of corner-cases where it might make sense.

It's why a lot of us say "code for Strict, deploy as 5".

Much less a lot of features you basically will want at some point - - CANVAS, AUDIO, VIDEO -- whilst pointlessly redundant to OBJECT, we're being forced to use thanks to browser support. It sucks that it's a wasteful extra tag in the specification, but in terms of functionality VIDEO is a must have.

There's a lot of stuff in 5 that you need that "should not have been implemented this way" but that we're pretty much forced to use because, well... what else is there? You want cross platform compatible audio and video, you're using HTML 5 because flash in the browser is dead. They shouldn't be their own tags as it defeats the entire "simplify the specification" ideal of 4 Strict, but it's what has been implemented so...

Even I've had to admit that 4 Strict is dead, but I try to uphold its ideals and ideas where possible by just not using the crappier aspects of HTML 5 that truly violate the intent.
"It is amazing what can be accomplished when nobody cares who gets the credit." -- Kelly Johnson

 

Advertisement