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

Closed
wants to merge 8 commits into
from

Projects

None yet

4 participants

@JAremko
Contributor
JAremko commented Mar 20, 2016

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



  • 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
Contributor
JAremko commented Mar 20, 2016

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 syl20bnr and 1 other commented on an outdated diff Mar 20, 2016
core/core-documentation.el
+ (insert (concat head-css-extra-readtheorg-head
+ (f-relative user-emacs-directory
+ (file-name-directory filename))
+ head-css-extra-readtheorg-tail)))))
+
+(defun spacemacs//pub-doc-html-advice (origfunc &rest args)
+ (save-current-buffer
+ (save-excursion
+ (let* ((filename (car (nthcdr 1 args)))
+ (visitingp (find-buffer-visiting filename)))
+ ;; Temporary "unvisit" the visited org files.
+ (when visitingp (with-current-buffer visitingp (setq buffer-file-name nil)))
+ (with-temp-buffer
+ (save-match-data
+ (insert-file-contents filename t)
+ (spacemacs//add-org-meta-readtheorg-css filename)
@syl20bnr
syl20bnr Mar 20, 2016 Owner

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

@JAremko
JAremko Mar 22, 2016 Contributor

done.

@syl20bnr
Owner

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

@robbyoconnor
Contributor

Merge conflicts :P

@JAremko
Contributor
JAremko commented Mar 20, 2016

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

@robbyoconnor
Contributor

Not with that attitude you don't!

@JAremko JAremko changed the title from Spacemacs documentation improvements and fixes. to [WIP] Spacemacs documentation improvements and fixes. Mar 21, 2016
@JAremko JAremko changed the title from [WIP] Spacemacs documentation improvements and fixes. to Spacemacs documentation improvements and fixes. Mar 22, 2016
@JAremko
Contributor
JAremko commented Mar 22, 2016

@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
Owner

Great move!

mrclean

@JAremko JAremko referenced this pull request Mar 23, 2016
@syl20bnr README.md: change links to spacemacs.org
Links to documentation sections can easily break since they are
indexed by their order (i.e. #orgheadline8)
3aff734
@JAremko
Contributor
JAremko commented Mar 25, 2016

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 ๐Ÿ˜ฟ

JAremko added some commits Mar 14, 2016
@JAremko JAremko fix typo b4c0cd2
@JAremko JAremko Remove query.stickytableheaders.js (error 404) d8b0e20
@JAremko JAremko Insert the readtheorg.css links wth html export advice
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.
c2388d0
@JAremko JAremko Make export to html compatible with GitHub and toc-org
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
50e9a1f
@JAremko JAremko Add Spacemacs docs minor mode to hide meta tags.
`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`
f6820c6
@JAremko JAremko Add org-mode link-type "https" to open local copies
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.
68be3a3
@JAremko JAremko Add the new .org example and a formatting script
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
3415779
@JAremko JAremko update README.org.template to the new convention
Remove #+HTML_HEAD_EXTRA: <link ... /readtheorg.css" />

:TOC_4_org:noexport: -> :TOC_4_gh:noexport:
4c521bb
@JAremko
Contributor
JAremko commented Mar 28, 2016

updated README.org.template 4c521bb

@syl20bnr syl20bnr changed the title from Spacemacs documentation improvements and fixes. to Fixes #4399 - Spacemacs documentation improvements and fixes. Mar 30, 2016
@syl20bnr
Owner

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! ๐ŸŽ‰

jaremko

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

@syl20bnr syl20bnr closed this Mar 31, 2016
@JAremko
Contributor
JAremko commented Mar 31, 2016

Thanks! ๐Ÿ˜Š

@JAremko JAremko deleted the JAremko:the-big-pull branch Mar 31, 2016
@robbyoconnor
Contributor

I love you all

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