Clojure

dev.clojure.org/display/doc/1. 3 renders badly

Details

  • Type: Enhancement Enhancement
  • Status: Closed Closed
  • Priority: Minor Minor
  • Resolution: Completed
  • Affects Version/s: Release 1.4
  • Fix Version/s: Release 1.4
  • Component/s: None
  • Labels:
    None
  • Patch:
    Code
  • Approval:
    Ok

Description

The page http://dev.clojure.org/display/doc/1.3 has markup issues:

  • *earmuffs* become bold
  • clearly [ ] must mean something special, 'cause they all turn pink.
  • presumably there's some way to make confluence use monospace for code snippets.
  • I'm sure confluence has some way to mark headings, but It doesn't look like "==" is it.
  • I'd like to evict the "frowning face" from CLJ-751's clj-format example.
  • 2.29 seems to have suffered some encoding debacle, though I'm not quite sure what happened.

Further discussion revealed that this was just a copy/paste of changes.txt in the source repository. Discussions on clojure-dev suggested the idea of recoding changes.txt to changes.md and recoding it as proper markdown so that it will be rendered nicely by github.

This would make http://dev.clojure.org/display/doc/1.3 obsolete, its contents could be replaced by a link to 'changes.md' on github. That makes more sense than maintaining two copies of the document in mutually incompatible markups (markdown and whatever confluence uses).

See also the following clojure-dev thread:

http://groups.google.com/group/clojure-dev/browse_thread/thread/ecf65c4e50d3fd76

Activity

Hide
Ben Smith-Mannschott added a comment -

0001-CLJ-838-changes.txt-recoded-as-markdown.patch

This recodes changes.txt as proper Markdown. Text is not hard-wrapped because github's Markdown dialect handles hard line breaks differently than standard Markdown. Also, the original wasn't hard-wrapped either.

0002-CLJ-838-rename-changes.txt-changes.md.patch

This patch just renames changes.txt to changes.md. I didn't want to rename and edit changes.txt in a single patch, not knowing how well git would handle that when it came time to apply the changes.

0003-CLJ-838-add-example-for-Add-docstring-support-to-def.patch

Meikel Brandmeyer provided an example of docstring support in def in response to my query, so I've included a patch to integrate that.

Show
Ben Smith-Mannschott added a comment - 0001-CLJ-838-changes.txt-recoded-as-markdown.patch This recodes changes.txt as proper Markdown. Text is not hard-wrapped because github's Markdown dialect handles hard line breaks differently than standard Markdown. Also, the original wasn't hard-wrapped either. 0002-CLJ-838-rename-changes.txt-changes.md.patch This patch just renames changes.txt to changes.md. I didn't want to rename and edit changes.txt in a single patch, not knowing how well git would handle that when it came time to apply the changes. 0003-CLJ-838-add-example-for-Add-docstring-support-to-def.patch Meikel Brandmeyer provided an example of docstring support in def in response to my query, so I've included a patch to integrate that.
Hide
Ben Smith-Mannschott added a comment -

I don't believe Markdown provides a good way of handling the contents section at the start of the document. I've improvised it by just formatting the thing as if it were a code sample.

Is the TOC really necessary? It's not ideal from a Don't Repeat Yourself standpoint. Also, manually maintaining the section numbers also strikes me as busy work? Can we do without?

Show
Ben Smith-Mannschott added a comment - I don't believe Markdown provides a good way of handling the contents section at the start of the document. I've improvised it by just formatting the thing as if it were a code sample. Is the TOC really necessary? It's not ideal from a Don't Repeat Yourself standpoint. Also, manually maintaining the section numbers also strikes me as busy work? Can we do without?
Hide
Ben Smith-Mannschott added a comment -

You can view a rendered version of changes.md here:

https://github.com/bpsm/clojure/blob/CLJ-838/changes.md

Show
Ben Smith-Mannschott added a comment - You can view a rendered version of changes.md here: https://github.com/bpsm/clojure/blob/CLJ-838/changes.md
Hide
Ben Smith-Mannschott added a comment -

patches updated for f0b092b66 "more changes.txt tweaks"

Show
Ben Smith-Mannschott added a comment - patches updated for f0b092b66 "more changes.txt tweaks"

People

Vote (0)
Watch (0)

Dates

  • Created:
    Updated:
    Resolved: