Fossil Forum

Embedded doc links to other embedded docs by repo-absolute path?
Login

Embedded doc links to other embedded docs by repo-absolute path?

(1) By Stephan Beal (stephan) on 2019-12-17 17:46:44 [source]

Consider this embedded doc link:

[](/foo/bar/baz.md)

The intention is to link to an embedded doc, so the path needs to be:

[](/doc/???/foo/bar/baz.md)

Where ??? really needs to be the same version as the embedded doc we're currently viewing. i.e. it needs to be ckout or trunk or tip or a version hash.

Do we have a link syntax to link to repo-absolute paths to embedded docs this way, or are relative paths the only way to do this:

[](../../foo/bar/baz.md)

:-?

(2) By TomaszDrozdz on 2019-12-18 09:44:08 in reply to 1 [link] [source]

You could tag some branch with "doc" tag.
Then You could use /doc/doc/foo/bar/baz.md

(3) By Stephan Beal (stephan) on 2019-12-18 10:25:11 in reply to 2 [link] [source]

That would tie any absolute-path links to the latest version of a given branch, though, which isn't what i'm trying to achieve (but might be useful in some other context).

When browsing files using the embedded docs links (/doc/branchName-or-version/...), fossil keeps you under that version, insofar as possible, when following links from one doc file to another, so it's possible to jump to /doc/someoldversion/... of a single doc then, by following the inter-doc links, browse the whole docs as they existed in that version. If i were to tag a branch and use absolute links in the form /doc/thattag/... then i would end up moving from the version i'm on to the tagged version (likely without noticing).

(4.1) By TomaszDrozdz on 2019-12-18 13:32:44 edited from 4.0 in reply to 1 [link] [source]

Maybe some fossil reserved tag like: sym-doc, so You could use it like that:
/doc/sym-doc/foo/bar/baz.md
so it would do what You want (it is keep selected by You check-in, branch, ...) ?

(5) By Stephan Beal (stephan) on 2019-12-18 13:33:32 in reply to 4.0 [link] [source]

That's along the lines of what i was thinking, maybe using characters which wouldn't be legal for a tag (if there are any such characters). AFAIK we don't currently have such a thing, but i may well be (and hopefully am) mistaken.

OTOH, there's no way, short of tracking it with a cookie, for fossil to know which version i was browsing. Hmmm.

(6) By Richard Hipp (drh) on 2019-12-18 15:14:31 in reply to 1 [link] [source]

In the latest trunk version of Fossil, please try links like this:

[](/doc/$SELF/foo/bar/baz.md)

See also the https://fossil-scm.org/fossil/doc/trunk/www/mdtest/test1.md document for test cases.

(7) By Richard Hipp (drh) on 2019-12-18 15:17:51 in reply to 6 [link] [source]

I wonder: Is $SELF the correct magic name here? Should it be changed to something like $CURRENTVERSION instead? If so, we need to do so before the next release, as once the code is released, it feature will be fixed.

Also, if anybody has objections to this enhancements, make your argument now so that it can be taken out before the next release.

(8) By ss48 on 2019-12-18 15:24:14 in reply to 7 [link] [source]

From what I understand, the feature would reference whatever embedded doc is checked out and active for the folder you are in when you open fossilui in that folder. If that's correct, $CURRENTVERSION seems a little subjective in this sense. Maybe $CHECKEDOUTVERSION or $ACTIVEVERSION would be better?

(10) By Stephan Beal (stephan) on 2019-12-18 17:14:43 in reply to 7 [link] [source]

I wonder: Is $SELF the correct magic name here?

After having looked over the diff...

Since the context of the replacement is so specific, and there's no chance of semantic mismatch, a single standalone $ looks like it would be much cleaner and easier to remember:

/doc/$/foo/bar/

/doc/{}/foo/bar also looks nice.

Sidebar: # would be ideal, but that collides semantically with URL fragments.

(11) By Florian Balmer (florian.balmer) on 2019-12-19 16:12:33 in reply to 7 [link] [source]

Is $SELF the correct magic name here?

What about $DOCREV, since the variable is specific to the /doc page? Or just $REV?

I know there's $ROOT, but $SELF is quite a general-purpose name, that may be useful for other features, in the future?

(12) By Stephan Beal (stephan) on 2020-02-10 09:48:18 in reply to 7 [link] [source]

I wonder: Is $SELF the correct magic name here? Should it be changed to something like $CURRENTVERSION instead? If so, we need to do so before the next release, as once the code is released, it feature will be fixed.

It turns out that there's a separate use case for this which isn't covered by the current code:

From within embedded docs, it's not terribly uncommon to want to do link to /dir/foo/bar?ci=XXX, where XXX == $SELF.

Of course, 99-ish times out of 100, ?ci=trunk suffices, so this isn't critical.

PS: if the name hasn't yet been cemented, $CURRENTVERSION is sounding more and more like a better choice than $SELF (which isn't bad in itself, but it may come across a vague in some contexts).

(13) By Richard Hipp (drh) on 2020-02-12 14:45:43 in reply to 12 [link] [source]

What about $CURRENT instead of $CURRENTVERSION?

(14) By Stephan Beal (stephan) on 2020-02-12 14:58:50 in reply to 13 [link] [source]

Sounds good to me.

(9) By Stephan Beal (stephan) on 2019-12-18 15:45:28 in reply to 6 [link] [source]

In the latest trunk version of Fossil, please try links like this:

Perfect!

This doesn't quite qualify as a bug, IMO, but is interesting:

For syntax highlighting support see [](/doc/$SELF/doc/highlightjs/README.md).

The resulting link is correct (points to /doc/ckout/...) but the resulting link label is /doc/$SELF/.... Such a link can probably considered an unusual corner case, and is trivial to work around in any case by providing an explicit label, so no harm done.

(That particular link was what got me wondering how to do this without a relative link (which also does the job, it just isn't as pretty).)

$SELF is fine by me. Maybe $$, which is the "this shell's process ID" variable in Unix shells. That's a bit cryptic, though. The shell variable $_ expands to the "last argument to the previous command," which would kinda make semantic sense here (in a cryptic sort of way), with doc' being the command and the version being the... well, the first argument, not the last.

i've got no strong feelings one way or the other - $SELF has a relevant meaning.