Content formatting - Githubissues

peteihis commented 5 years ago

The page formatting should be unified and visually clarified.

Most of the texts are spread edge to edge without any margins but some paragraphs are placed in tables. Then the width of a table cell is sometimes limited and sometimes not. Look at the Rendering-section for example.
The pages are also real "old-skåål" in the sense, that they have been written before .css-technique.
Navigating between sections could be improved, so you don't always have to back with the browser to get to the table of contents to find your next point of interest.

There may be a few challenges in getting it right as sometimes the visualization needs to take it's own space. However I'd suggest to:

Use proper margins (100 px ?)
Limit the content width readable
Use .css(es)
Add navigation bars
Review the used fonts. For reference, GitHub is using the best on-screen fonts I have seen so far.

At first I'd probably suggest .css:es. On the longer run we might consider php to collect the content of each page. That part is quite logical and effortless to use but php also offers a lot of toys, that probably would not be useful in this case (fancy ways of animating page changes etc).

Low level browser adaptation should be good enough and no device dependent adaptation. I think it is safe to assume tabletop or laptop usage and not so much pocket size devices. (Though, setting it up to recognize the platform is not that difficult but then we'd go JavaScript. Androids mostly respond in a predictable manner, but the late Windows phones were an ultimate disaster in interpreting the mark-up code.)

peteihis commented 5 years ago

On the longer run we might consider php

Of course php does not work if you download the manual. Got to study css a bit furter, there seems to be a lot available in there. Also a very closely related question is, which html version we should build it on? For example frames don't exist in html-5. Instead css provides very similar functions, that probably work even better.

My feelings are that we'd pretty much head for the latest inventions. What we do here now will be there in 2039.

Sailsman63 commented 5 years ago

I agree that this should be improved.

However, if we want to continue using the help plugin, we need to stick to HTML 2.1 (Java support issues) Whether we do want to continue with the help plugin is a discussion for the broader community, post-3.1.

peteihis commented 5 years ago

HTML 2.1

Most of the files come with this 'meta-info' or what ever...

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

Some (quick display pages mostly) are "just plain html".

Whether we do want to continue with the help plugin

Hmm... In the ROW help usually launches the default www-browser. Most of them read the content online.

Sailsman63 commented 5 years ago

Keep in mind that the metadata is just that... Metadata. The HTML renderer will simply ignore tags that it does not understand. As long as the formatting tags all existed in HTML 2, they will renderer properly.

Rebuilding how help works looks like a bigger project, I'm personally not opposed to using the system browser, but let's see what comes out of the community.

peteihis commented 5 years ago

I had a look at the Help code. The parts of the manual, that have been copied to Help have been edited by a html-tool and even though both the original and the help-version look rather messy, it's a different kind of a mess. One other problem are the translations. At least some of the .es and .it files actually are in English. --> Not worth keeping the Help as a bottle-neck, when working on the manual.

Rebuilding how help works looks like a bigger project

You could say that again.

ArtOfIllusion / Manual

Content formatting #5