docs: Move language references to a Reference section #5375

jennings · 2025-01-15T23:22:51Z

I think the reference pages for the revset, fileset, and templating languages are different concerns from the configuration reference pages.

As suggested by @arxanas, I've moved the language descriptions into a new Reference section.

Then I created new pages revset-aliases.md and template-aliases.md in the Configuration section for the well-known aliases like immutable_heads(), format_timestamp(), etc.

jennings · 2025-01-16T00:22:48Z

The "Check that MkDocs..." build failure seems caused by this issue: astral-sh/uv#10654

martinvonz · 2025-01-16T00:38:39Z

Seems like @ilyagr should review this (others can of course also review). Will you have time to look at this?

ilyagr · 2025-01-16T00:48:13Z

Could you rebase? I'd like to know whether CI will pass now that uv 0.5.20 was released (I'm guessing CI will run after a rebase, hopefully? Though maybe github actions are simply down; I think I saw similar symptoms caused by that once).

Since 0.5.19 was the newest version for less than a day, perhaps we can ignore its existence...

Update: By the way, the check that uses the latest version of uv is not supposed to be required anyway.

ilyagr

Thanks, splitting config.md sounds great to me! A reference section also sounds great.

I had a bunch of minor comments. There's also a comment I marked as "Open-ended confusion" about [revsets] and [templates] that I'm not sure what to do about.

docs/config.md

docs/template-aliases.md

docs/revset-aliases.md

docs/config.md

docs/template-aliases.md

ilyagr · 2025-01-16T04:12:26Z

docs/revset-aliases.md

+"trunk()" = "dev@origin"
+```
+
+## `immutable_heads()`


This seems like it would be cryptic to a new reader.

Perhaps something like "immutable_heads(): changing the set of immutable commits"? Or maybe have a redundant subheading:

## Changing the set of immutable commits ### `immutable_heads()`

I was concerned about breaking links if we rephrase it. This anchor is #immutable_heads, but adding more text would lead to #immutable_heads-changing-the-set-of-immutable-commits, which would break if we rephrase it to, say, "immutable_heads(): Set of immutable commits".

I didn't see a way to control what anchor MkDocs uses. Ideally, the anchor would be #immutable_heads but the visible text would be more descriptive.

What do you think?

I was also worried a bit, perhaps the "redundant subheading" option might help. If we can't figure out an ideal solution, I think readability is more important than potential changes to heading anchors.

I also don't know a good way to affect MkDocs anchors or add new ones. We could use HTML, problably, but that'd be terrible for reading the docs in the terminal.

Ah! I found how to set anchors with just markdown:

### `immutable_heads()`: Set of immutable commits {#immutable_heads}

I've added more descriptive text to both trunk() and immutable_heads().

docs/revset-aliases.md

docs/config.md

yuja · 2025-01-22T12:51:41Z

mkdocs.yml

+      - 'Revset language': 'revsets.md'
+      - 'Fileset language': 'filesets.md'
+      - 'Templating language': 'templates.md'


nit: just sort them in lexicographical order?

Sure. I was thinking to sort them by "importance" but there's only three so it really doesn't matter.

yuja · 2025-01-22T12:56:57Z

docs/config.md

-'format_time_range(time_range)' = 'time_range.start() ++ " - " ++ time_range.end()'
-```
+You can use relative timestamps by adjusting the [`format_timestamp()` template
+alias](template-config.md#format_timestamp).


Do we need links per sub section? I think something like this is good enough:

## Log ... ### Template and style See [Log template configuration](..) for details .. blah blah

I think related config variables can also be moved there. For example, ui.log-word-wrap is NOT a template parameter, but it applies to log template output.

This is a request to remove headings like "Relative timestamps", "Author format", etc., and just have one blanket section "Template and style" that links over to the template-config.md page. Do I understand correctly?

@ilyagr suggested keeping these headings so incoming links don't break, like the link to #node-style that jj log --help outputs.

But, now that I've found how to add custom anchors to the page, I could make all those anchors go to the relevant blanket section.

### Template and style [](){#relative-timestamps}[](){#author-format}... See [Log template configuration](template-config.md) for more information.

What do you think?

This is a request to remove headings like "Relative timestamps", "Author format", etc., and just have one blanket section "Template and style" that links over to the template-config.md page.

Yes. I don't think we would want to update both config.md and template/revset-config.md when adding new sections.

yuja · 2025-01-22T12:57:53Z

docs/config.md

-'commit_timestamp(commit)' = 'commit.author().timestamp()'
-```
+The [`commit_timestamp()` template alias](template-config.md#commit_timestamp)
+controls whether the author or committer timestamp is displayed in the log.

 ### Signature format


Move "Signature format" to template-config.md?

yuja · 2025-01-22T13:04:29Z

docs/template-config.md

+
+This configuration section configures the default. These values can use [template
+aliases](#template-aliases).
+


I think it's better to briefly describe the overview of the [templates] section. For example, we had this in the original doc:

You can configure the template used when no `-T` is specified. - `templates.log` for `jj log` - `templates.op_log` for `jj op log` - `templates.show` for `jj show` [templates] # Use builtin log template log = "builtin_log_compact" # Use builtin op log template op_log = "builtin_op_log_compact" # Use builtin show template show = "builtin_log_detailed"

I also think we should omit detailed section unless there are things to be documented. For example, the ### Show section is pretty much empty.

…page

ilyagr · 2025-01-28T08:31:53Z

Ah! I found how to set anchors with just markdown <https://www.mkdocs.org/about/release-notes/#anchors>:

I was initially very excited about this (thanks for finding it!), but now I'm a bit frozen on this point (or, in more professional terms, undecided about what is best to do here 👔). I might write more later, but TLDR: - This syntax is *not* part of CommonMark, and is not supported by GitHub. It's probably not supported by VS Code, etc. There are some discussions about adding something like this to CommonMark, but they died down years ago, and CommonMark is no longer accepting new features (not sure whether this is a temporary or a permanent state). - This syntax is supported by MkDocs and [Docusaurus](https://docusaurus.io/docs/markdown-features/toc#heading-ids) (which is my best guess at a CommonMark-based doc builder we could use that has versioning, even though I don't like its heavy reliance on React&JS magic) - This syntax would look OK if we printed the files unformatted to stdout (like we might be doing with `jj help --topic`). The HTML `<a id="raw-anchor"></a>` syntax, also explained in Stephen's links, - should be supported by any HTML-destined Markdown system. - We'd probably have to find a way to remove it if we print the Markdown to stdout or if we ever want to convert it via Pandoc. - I haven't tested it, but hopefully MkDocs will recognize these anchors and won't label links to them as broken. - Not sure about VS Code I'm not sure whether we should use one of these, or just grit our teeth and only use the anchors given by headings, which everything understand, but would mean that we should try to get the heading structure right the first time (though we shouldn't overdo it either, it's not the end of the world if people have to use their eyes to search through the page, especially if we make it shorter). Sorry for a sleepy comment with runon sentences. (I also posted this in a weird way since I had a half-written review that got interrupted by thinking about these points)

steveklabnik · 2025-01-28T17:26:01Z

Just a few brief comments, @ilyagr :

This syntax is not part of CommonMark, and is not supported by GitHub.

If I type <http://example.com> here: http://example.com it does link on GitHub.

While I don't see it in the CommonMark specification, their "dingus" does in fact render properly too, you can try it here https://spec.commonmark.org/dingus/

In my Windows Terminal, running bash in Ubuntu, links like this are clickable, when I hover over this, it gets underlined, and when I click it, it does open the link in my browser:

even though I don't like its heavy reliance on React&JS magic

A nice thing about Docasaurus is that it's primarily server-side rendered, so I'm not sure which parts you object to, but it's all at build time, not in the browser.

Rust's own comment style guidlines for APIs suggest using [][] links over []() ones, but I (who authored this) forgot about <> links, so they were never considered https://rust-lang.github.io/rfcs/0505-api-comment-conventions.html

ilyagr · 2025-01-28T23:20:26Z

@steveklabnik I meant the "specifying the anchor" syntax, {#anchor}.

Aside: As a test, here is a link to two ids below: first id, second id. The first one does not work, the second one does

You can see the GitHub markdown rendering here failing here for {#trunk} (it should not be shown):

You can also see it below.

Here are the targets of the above links

The source is:

### This anchor does not work {#my-custom-heading-id}

<a id="my-very-custom-heading-id"></a> `<<<` There is an invisible anchor here

This anchor does not work {#my-custom-heading-id}

<<< There is an invisible anchor here

jennings force-pushed the jennings/push-vppqntkptzzw branch 2 times, most recently from 69193a1 to 3faa39f Compare January 15, 2025 23:29

jennings force-pushed the jennings/push-vppqntkptzzw branch from 3faa39f to 46ac4a5 Compare January 16, 2025 00:35

ilyagr reviewed Jan 16, 2025

View reviewed changes

jennings force-pushed the jennings/push-vppqntkptzzw branch 4 times, most recently from d56baae to b5b9c4f Compare January 22, 2025 05:52

jennings requested review from yuja and ilyagr January 22, 2025 05:55

istudyatuni reviewed Jan 22, 2025

View reviewed changes

docs/config.md Outdated Show resolved Hide resolved

yuja reviewed Jan 22, 2025

View reviewed changes

jennings added 3 commits January 22, 2025 22:43

docs: Move language references to a Reference section

939f404

docs: Extract well-known template aliases to their own configuration …

98c2881

…page

docs: Extract well-known revset aliases to their own page

d38baae

jennings force-pushed the jennings/push-vppqntkptzzw branch from b5b9c4f to d38baae Compare January 23, 2025 06:45

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Move language references to a Reference section #5375

docs: Move language references to a Reference section #5375

jennings commented Jan 15, 2025

jennings commented Jan 16, 2025

martinvonz commented Jan 16, 2025

ilyagr commented Jan 16, 2025 •

edited

Loading

ilyagr left a comment •

edited

Loading

ilyagr Jan 16, 2025

jennings Jan 16, 2025

ilyagr Jan 23, 2025

jennings Jan 23, 2025

yuja Jan 22, 2025

jennings Jan 22, 2025

yuja Jan 22, 2025

jennings Jan 23, 2025

yuja Jan 23, 2025

yuja Jan 22, 2025

yuja Jan 22, 2025

ilyagr commented Jan 28, 2025 via email •

edited

Loading

steveklabnik commented Jan 28, 2025 •

edited

Loading

ilyagr commented Jan 28, 2025 •

edited

Loading


		This configuration section configures the default. These values can use [template
		aliases](#template-aliases).

docs: Move language references to a Reference section #5375

Are you sure you want to change the base?

docs: Move language references to a Reference section #5375

Conversation

jennings commented Jan 15, 2025

jennings commented Jan 16, 2025

martinvonz commented Jan 16, 2025

ilyagr commented Jan 16, 2025 • edited Loading

ilyagr left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ilyagr commented Jan 28, 2025 via email • edited Loading

steveklabnik commented Jan 28, 2025 • edited Loading

ilyagr commented Jan 28, 2025 • edited Loading

Here are the targets of the above links

This anchor does not work {#my-custom-heading-id}

ilyagr commented Jan 16, 2025 •

edited

Loading

ilyagr left a comment •

edited

Loading

ilyagr commented Jan 28, 2025 via email •

edited

Loading

steveklabnik commented Jan 28, 2025 •

edited

Loading

ilyagr commented Jan 28, 2025 •

edited

Loading