[tahoe-lafs-trac-stream] [Tahoe-LAFS] #2835: links in INSTALL don't work on both github and readthedocs

[Tahoe-LAFS]

#2835: links in INSTALL don't work on both github and readthedocs
-------------------------------+--------------------
     Reporter:  warner         |      Owner:
         Type:  defect         |     Status:  new
     Priority:  normal         |  Milestone:  1.12.0
    Component:  documentation  |    Version:  1.11.0
   Resolution:                 |   Keywords:
Launchpad Bug:                 |
-------------------------------+--------------------

Comment (by warner):

 For reference, I think https://github.com/github/markup might define how
 github does rendering.

 I haven't yet found a syntax that works in both places, because
 !ReadTheDocs (which is really just Sphinx-as-a-service) generates/serves
 .html files, whereas !GitHub knows the files by their original .rst names.
 Sphinx knows which files it has translated, so a `:doc:` link will point
 to the post-translation name (.html), but !GitHub has no such translation.

 My inclination at this point is to use !ReadTheDocs syntax, and add a
 docs/README that says "if you're reading this on github, please follow
 this link to readthedocs instead, where the hyperlinks will be rendered
 properly". And maybe add a single extra link or two from just the INSTALL
 doc (i.e. provide both syntaxes) if we think it's likely that many people
 will end up reading it there.

--
Ticket URL: <https://tahoe-lafs.org/trac/tahoe-lafs/ticket/2835#comment:1>
Tahoe-LAFS <https://Tahoe-LAFS.org>
secure decentralized storage