Fixes #4399 - Spacemacs documentation improvements and fixes. #5545

JAremko · 2016-03-20T00:59:41Z

The prime goal of this PR is to fix the Spacemacs documentation links in the Table Of Content at GitHub and introduce reliable method of linking headings from different files that will work in the Spacemacs and both at GitHub and spacemacs.org web sites.

I fixed all the merge conflict except the last commit (it's too global and will constantly brake)

In the discussion #4399 we came to the conclusion that the solution shouldn't modify local files in the Spacemacs installation - they should be the same locally and at the repository. Also we decided to use toc-org for table of content.

Since we can't change how GitHub handles links, I made Spacemacs and spacemacs.org use the GitHub style links - they should always work at GitHub. Also I added some of my PRs that overlaps with this one and smashed bugs, fixed typos that I encountered while implementing the fix. They all are in the separate commits so it shouldn't be a problem.

I'll explain each of the commits

fix typo 3b5ffac it fixes typo.

Remove query.stickytableheaders.js (error 404) ebad4eb it causes 404 error at the Spacemacs website(open web-browser console to see it) The file isn't there anymore, but it's not crucial and the website should be fine without it.

Insert the readtheorg.css links wth html export advice 2012530 Many README.org files of the Spacemacs layers have wrong links to the readtheorg.css file. Also it adds unnecessary clutter The commit adds or fixes (if it's already there) the link during the export to html process. Also it implements a wrapper function that can chain all kind of the org file preprocessors (used later)

add TOC to Semantic layer bfe1d73 it was missing. Now it's not.

Make export to html compatible with GitHub and toc-org d0abe2e this commit adds the export preprocessors:
- spacemacs//toc-org-unhrefify-toc - makes TOC_gh normal org TOC again.
- spacemacs//reroot-links - If a link refers an org file or its heading and the file is in the Spacemacs GitHub repository, the function will rewrite the base of the link to http://spacemacs.org/ | example | exported org file.
- spacemacs//org-heading-annotate-custom-id - adds GitHub style ids to the exported headings so they can be referred in the same way as at the GitHub web site. For the more info read the commit message.

Add Spacemacs docs minor mode to hide meta tags. b8f0ea7 When the mode is enabled, it hides nonsense in the docs:
- Off (the image is clickable)
- On (the image is clickable)

Add org-mode link-type "https" to open local copies 59ae423 this is an org-mode https link type handler that brings GitHub links to the Spacemacs(including links to headings) In a similar fashion to spacemacs//reroot-links if a link refers an org file or its heading and the file is in the Spacemacs GitHub repository, the handler will open the local copy of the file with spacemacs/view-org-file(this is how SPC h SPC opens them) or if it's not in there - the link will be opened in the browser. The function spacemacs/view-org-file applies visual enhancements like the indent mode and space-doc-mode so the opened files also will be prettified. And since those are the GItHub style links they will work at the GitHub, Spacemcs and spacemacs.org. For example:
- [[https://github.com/syl20bnr/spacemacs/blob/master/doc/FAQ.org#os-x][Link to FAQ "OS X" heading]] leads to (the image is clickable)
- but [[https://www.google.com][Link to www.google.com]] leads to https://www.google.com
  This is more reliable and flexible way to link files and headings than the default org-mode one - if we want it to work at the GitHub, in the Spacemacs and at its web site. + it adds pretifiers.

Remove #+HTML_HEAD_EXTRA: readtheorg.css 100bc0a now we don't need them.

Set org files TOC to :TOC_4_gh:noexport: 88e5ff9 This way toc-org will build GitHub TOC when the org files are saved.

~~PR TEST COMMIT~~ 1706d3f toc-org-gh.el script for the applying toc-org to all the org files in the batch mode and example files for the PR. You can call the script from the repo root with find . -name "*.org" -type f -exec emacs -batch -l ./doc/pr-test/toc-org-gh.el '{}' -f toc-apply \;

format .org TOCs with toc-org 402bba5 Contains org files processed with toc-org-gh.el - not for merge. Can be easily reproduced by running the script. Probably should be split into a couple of commits, because it makes git crush - too many changes?

This is my magnum opus. Those lines shall be carved on my tombstone 😄

@syl20bnr @TheBB @StreakyCobra @a13ph @robbyoconnor @d12frosted and everyone else! Be the witnesses of my glory or the miserable failure!

JAremko · 2016-03-20T01:05:30Z

We should discuss it. And if this is a proper way to go around - I'll write about the links in the Contributor guidelines and add .org validations to the Travis test suite.

Also the most of the commits can be safely cherry picked.

syl20bnr · 2016-03-20T01:41:18Z

core/core-documentation.el

+        (with-temp-buffer
+          (save-match-data
+            (insert-file-contents filename t)
+            (spacemacs//add-org-meta-readtheorg-css filename)


You can add a comment here to specify that any preprocess function should be added here.

syl20bnr · 2016-03-20T01:43:48Z

A quick look at the PR tells me that it is pretty much what I wanted, nice work 👍
Kudos for the script!

robbyoconnor · 2016-03-20T02:21:50Z

Merge conflicts :P

JAremko · 2016-03-20T02:23:57Z

@robbyoconnor Ya it's the last commit. It should be ditched anyway - I have no hope to keep it synced 😄

robbyoconnor · 2016-03-20T06:24:19Z

Not with that attitude you don't!

JAremko · 2016-03-22T01:20:46Z

@syl20bnr I removed commits that change .org files and improved the formatting script.
Now you just need to run bash ./doc-fmt/run.bash and it will:

remove #+HTML_HEAD_EXTRA ... readtheorg.css" />
replace :TOC_4_org: with :TOC_4_gh:
apply toc-org

This way the PR shouldn't get conflicts so often.

syl20bnr · 2016-03-22T01:32:06Z

Great move!

Links to documentation sections can easily break since they are indexed by their order (i.e. #orgheadline8)

JAremko · 2016-03-25T08:54:40Z

Dropped add TOC to Semantic layer bfe1d73 because the layer was nuked or moved in develop.

Also squashed my refactorings.

Ahh... The org layer also moved. Cool 😿

It removes the need to clutter Spacemacs documentation with Also it reduces the amount of bugs, because it's hard to get the path right.

Add new html preprocessors to the org-html-publish-to-html pipeline: - `spacemacs//toc-org-unhrefify-toc` - remove the `toc-org` modifications for the TOC - `spacemacs//org-heading-annotate-custom-id` - annotate org headings with the indexes that GitHub uses for linking. `org-html-publish-to-html` will use them instead of the default `#orgheadline{N}`. This way the GitHub links and the http://spacemacs.org/ links will be compatible." - `spacemacs//reroot-links` - find the links that start with https://github.com/syl20bnr/spacemacs/blob/ and end with .org{#an-optional-heading-link} (i.e the links between the local org files). Change their root to http://spacemacs.org/ so the links will point at files located on the site. *For the "file to file" links to work properly the expor

`space-doc-mode` - Buffer local minor mode for Spacemacs documentation files. The mode hides org meta tags. Enabled when viewing documentation via `SPC` `h` `SPC`

The https link-type opens the local copies of the Spacemacs documentation files with the spacemacs/view-org-file function. It supports GitHub style heading links For example, the link: https://github.com/syl20bnr/spacemacs/blob/develop/layers/org/README.org#links Will be handled similary to as if it was: file:~/.emacs.d/layers/org/README.org::*links Also the `space-doc' mode will be applied. Refactored GH style anchor search.

Add ./doc-fmt/ folder that contains the .org example and the script(run.bash) that should be run from the repo root. Its purpose: - remove #+HTML_HEAD_EXTRA: ... readtheorg.css" /> - replace :TOC_4_org:noexport: with :TOC_4_gh:noexport: - apply the gh style TOC

Remove #+HTML_HEAD_EXTRA: <link ... /readtheorg.css" /> :TOC_4_org:noexport: -> :TOC_4_gh:noexport:

JAremko · 2016-03-28T06:21:53Z

updated README.org.template 4c521bb

syl20bnr · 2016-03-31T03:50:37Z

One of my favorite PR, clean and fun to merge. Great job 💜
I ran the script on the doc files and it worked great. Also the new preprocessors fixed some wrong CSS paths 👍
So this is it, we have links working in Emacs and Github! 🎉

Thank you !
Cherry-picked into develop branch, you can safely delete your branch.

JAremko · 2016-03-31T03:55:45Z

Thanks! 😊

robbyoconnor · 2016-04-14T04:24:43Z

I love you all

JAremko mentioned this pull request Mar 20, 2016

Broken links in some .org files #4399

Closed

syl20bnr reviewed Mar 20, 2016
View reviewed changes

StreakyCobra added the Bug fix label Mar 20, 2016

JAremko force-pushed the the-big-pull branch 2 times, most recently from fc12926 to 8cf294b Compare March 21, 2016 21:41

JAremko changed the title ~~Spacemacs documentation improvements and fixes.~~ [WIP] Spacemacs documentation improvements and fixes. Mar 21, 2016

JAremko force-pushed the the-big-pull branch from 8cf294b to b5efcfc Compare March 22, 2016 01:05

JAremko changed the title ~~[WIP] Spacemacs documentation improvements and fixes.~~ Spacemacs documentation improvements and fixes. Mar 22, 2016

JAremko force-pushed the the-big-pull branch 4 times, most recently from cf11885 to e9f9a53 Compare March 22, 2016 05:06

JAremko referenced this pull request Mar 23, 2016

README.md: change links to spacemacs.org

3aff734

Links to documentation sections can easily break since they are indexed by their order (i.e. #orgheadline8)

JAremko force-pushed the the-big-pull branch 4 times, most recently from b000bb4 to 74c2359 Compare March 25, 2016 08:53

JAremko force-pushed the the-big-pull branch from 74c2359 to 39dd452 Compare March 25, 2016 09:38

JAremko added 4 commits March 28, 2016 09:09

fix typo

b4c0cd2

Remove query.stickytableheaders.js (error 404)

d8b0e20

Insert the readtheorg.css links wth html export advice

c2388d0

It removes the need to clutter Spacemacs documentation with Also it reduces the amount of bugs, because it's hard to get the path right.

JAremko added 4 commits March 28, 2016 09:09

Add Spacemacs docs minor mode to hide meta tags.

f6820c6

`space-doc-mode` - Buffer local minor mode for Spacemacs documentation files. The mode hides org meta tags. Enabled when viewing documentation via `SPC` `h` `SPC`

update README.org.template to the new convention

4c521bb

Remove #+HTML_HEAD_EXTRA: <link ... /readtheorg.css" /> :TOC_4_org:noexport: -> :TOC_4_gh:noexport:

JAremko force-pushed the the-big-pull branch from 39dd452 to 4c521bb Compare March 28, 2016 06:20

syl20bnr changed the title ~~Spacemacs documentation improvements and fixes.~~ Fixes #4399 - Spacemacs documentation improvements and fixes. Mar 30, 2016

syl20bnr closed this Mar 31, 2016

JAremko deleted the the-big-pull branch March 31, 2016 05:47

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fixes #4399 - Spacemacs documentation improvements and fixes. #5545

Fixes #4399 - Spacemacs documentation improvements and fixes. #5545

JAremko commented Mar 20, 2016

JAremko commented Mar 20, 2016

syl20bnr Mar 20, 2016

JAremko Mar 22, 2016

syl20bnr commented Mar 20, 2016

robbyoconnor commented Mar 20, 2016

JAremko commented Mar 20, 2016

robbyoconnor commented Mar 20, 2016

JAremko commented Mar 22, 2016

syl20bnr commented Mar 22, 2016

JAremko commented Mar 25, 2016

JAremko commented Mar 28, 2016

syl20bnr commented Mar 31, 2016

JAremko commented Mar 31, 2016

robbyoconnor commented Apr 14, 2016

Fixes #4399 - Spacemacs documentation improvements and fixes. #5545

Fixes #4399 - Spacemacs documentation improvements and fixes. #5545

Conversation

JAremko commented Mar 20, 2016

I'll explain each of the commits

This is my magnum opus. Those lines shall be carved on my tombstone 😄

@syl20bnr @TheBB @StreakyCobra @a13ph @robbyoconnor @d12frosted and everyone else! Be the witnesses of my glory or the miserable failure!

JAremko commented Mar 20, 2016

syl20bnr Mar 20, 2016

Choose a reason for hiding this comment

JAremko Mar 22, 2016

Choose a reason for hiding this comment

syl20bnr commented Mar 20, 2016

robbyoconnor commented Mar 20, 2016

JAremko commented Mar 20, 2016

robbyoconnor commented Mar 20, 2016

JAremko commented Mar 22, 2016

syl20bnr commented Mar 22, 2016

JAremko commented Mar 25, 2016

JAremko commented Mar 28, 2016

syl20bnr commented Mar 31, 2016

JAremko commented Mar 31, 2016

robbyoconnor commented Apr 14, 2016