Readme format add docs webview

a-b-street / osm2lanes

A common library and set of test cases for transforming OSM tags to lane specifications

https://a-b-street.github.io/osm2lanes/

Apache License 2.0

34 stars 2 forks source link

Readme format add docs webview #47

Closed tordans closed 2 years ago

tordans commented 2 years ago

Minor changes and additions to the readme.

enzet commented 2 years ago

Sorry, but I don't agree with header changes. The readme file was deliberately using === and --- syntax for first and second level heading and never used ##, so it was consistent. I subjectively consider them more human-readable.

Don't you mind if I'll get headers back?

Anyway, thank you for contributing! Just my personal preference.

dabreegster commented 2 years ago

Don't you mind if I'll get headers back?

No preference from my end

tordans commented 2 years ago

Don't you mind if I'll get headers back?

I don't mind.

I also don't agree. :-) Using dashes for all headlines is what I see in most .md files. It is super easy to scan and understand (and learn): one hash = h1, two hashes h2 and so on. With the = and - I need to look up which is what. And then I am wondering if the length of the line needs to be aligned with the word… And when scanning I see those as separators ---, not headline indicators.

droogmic commented 2 years ago

I enjoy adding fuel to a pedantic discussion, so my opinion:

markdown is a terrible markup language (see any of the many blog posts: https://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/), last I did research I think I liked asciidoc the most.
if we do use markdown, it is because it is the default on github, so let's just do what they say: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax

enzet commented 2 years ago

Well OK, I give up. :)

GitHub Docs look convincing.