New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

HTML version of the docs is confusing #110

Open
ilyaza opened this Issue Jan 22, 2019 · 5 comments

Comments

Projects
None yet
2 participants
@ilyaza
Copy link

ilyaza commented Jan 22, 2019

It looks like the formatting in the HTML version of the docs is a direct translation of the formatting for a CLI version. The ticks around chunks of “CODE” are very confusing!

It is long understood how to format code in HTML:

  • use a different font;
  • use a different color;
  • use a different background.

The first two are already used — so all one needs is to drop the ticks, and add a different background.

@ilyaza ilyaza changed the title HTML version of docs is confusing HTML version of the docs is confusing Jan 22, 2019

@ilyaza

This comment has been minimized.

Copy link
Author

ilyaza commented Jan 22, 2019

In fact, the leading - and . in itemizations are also from pre-Unicode era, and are also confusing! Better change to •, ☆ etc. — or just use native HTML itemized lists.

@dtschump

This comment has been minimized.

Copy link
Owner

dtschump commented Jan 23, 2019

The doc is indeed generated automatically from a raw ASCII documentation, so it's now always simple to format it correctly for a HTML output. I've done my best.
I've re-worked a little bit on the formatting though, following some of your suggestions : https://gmic.eu/reference.shtml

@ilyaza

This comment has been minimized.

Copy link
Author

ilyaza commented Jan 23, 2019

Thanks! — but I do not understand: a lot of times the second level of itemized lists is marked with ∘, but in https://gmic.eu/reference.shtml#section9 it is different: it is still _

@dtschump

This comment has been minimized.

Copy link
Owner

dtschump commented Jan 23, 2019

Indeed. I'll try to fix that as well.

@ilyaza

This comment has been minimized.

Copy link
Author

ilyaza commented Jan 23, 2019

Two more:

(A) the “link” character 🔗 does not show in Chrome on Win7. (I maintain a lot of resources for access to Unicode, but apparently, it is not even possible to customize Chrome! AFAIU, it should be done on the level of OS to “crosslink some fonts together”. At least with the customizations linked to above, everything shows fine in Firefox.)

This is what GitHub is using to show this character:

<g-emoji class="g-emoji" alias="link" fallback-src="https://github.githubassets.com/images/icons/emoji/unicode/1f517.png">
   <img class="emoji" alt="link" height="20" width="20" src="https://github.githubassets.com/images/icons/emoji/unicode/1f517.png">
</g-emoji>

(B) In https://gmic.eu/reference.shtml#subsection22, formatting is still “the old one”.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment