Page MenuHomePhabricator

Remarkup help/reference link goes to secure.phabricator.com instead of local
Open, WishlistPublic

Description

The help/ button in remarkup text fields of my local phab instance points to https://secure.phabricator.com/diviner/find/?name=Remarkup+Reference&type=article&jump=1 which then goes to https://secure.phabricator.com/book/phabricator/article/remarkup/.

Instead it should go to my installations reference page. My company's workstations don't generally have internet access so this means users have to track down the correct path themselves.

I check and the doc page does exist locally.

Steps to reproduce:

  1. open the new task form on a non-phacility installation, e.g. https://phabricator.wikimedia.org/
  2. click the icon in the Description field
  3. note that you're now on secure.phabricator.com

Event Timeline

epriestley added a subscriber: epriestley.
epriestley triaged this task as Wishlist priority.

It is very unusual for documentation to exist locally, as generating it currently requires building xhpast and doing setup on Diviner.

I think it is also very unusual for workstations to not be connected to the internet.

You can change PhabricatorEnv::getDoclink() locally as a workaround. We may try to send users to a local documentation source in the future if we detect that the docs have been built, but don't currently expect installs to build it or keep it up to date.

I see. At least some of the individual help pages (e.g. https://secure.phabricator.com/applications/mailcommands/PhabricatorManiphestApplication/task/ are linked locally but I guess those are part of the app instead of inside Diviner.

It would be nice if the Remarkup docs were similarly available in normal installs but I recognize that my use case isn't typical.

Yeah, the local help pages aren't generated by Diviner -- they're generally generated from the configured code at runtime.

In theory we could make the Remarkup rules self-documenting like that, but I'd guess the result would be less organized than the current human-facing document. Still, we might pursue that at some point.

Once someone asked me why the icon spin wasn't working, as it was documented but our install hadn't upgraded with that feature yet. It was the most devastating sadface I'd ever seen on IRC.

Not a problem that's caused me any concern. As an alternate solution, would you consider versioning Remarkup and having the documentation indicate what version the features are on?

Err I guess the two problems are exactly the same.

Yeah, they're hard to separate -- available rules depend on configuration, installed/uninstalled applications, extensions, and version, and individual rule behaviors may depend on things like the presence of dependencies on the system (for example, whether cowsay works, and which cows are available).

Although most of these are probably somewhat self-evident, it wouldn't be sufficient to only differentiate on version.