Undocumented internal macros in TeXmacs (wiki)

#1

This post is devoted to a collection of undocumented TeXmacs internal macros, hopefully this will help the documentation of TeXmacs. The idea is to keep it around here as a wiki post (i.e. editable by everybody) and maybe at a later stage integrate these informations in the blog or directly improve the documentations.

  1. (render-footnote* sym nr body). src. Generate a footnote like

sym. body

where sym is the preceding symbol and body is the text of the footnote. It will generate a label whose name is concatenating “footnote-” and the value of nr, referring to the location of the footnote. We have, on the other hand, a label whose name is concatenating “footnr-” and the value of nr, to which the sym in the footnote refers. This label is used to back-refer the footnote (that is to say, where we need this footnote).

  1. (render-footnote nr body) src. Invoking render-footnote* with sym=nr, nr=nr and body=body.

(It would be interesting to document the following tags, in particular the whole locus support)

  1. locus
  2. id, url used as argument of locus macro, have no effect alone.
  3. hard-id generate a hash from given text, this hash could change when document is reopened.
  4. (set-binding key value) this macro will try to put a pair of key-value into references collection of current document.
  5. link have no effect alone
  6. script
  7. doc-authors (not doc-author) this macro is used as “style macro”, which customize rendering of multiple authors, like render-* macros.
4 Likes
Experimental TeXmacs wiki
References to arbitrary points in the document
Proposal: bi-directional link feature
[wiki] Assorted code snippets to customize TeXmacs' behaviour
#2

Could this be a good post for “TeXmacs notes” to which people can contribute gradually?

#3

Maybe it is useful to keep it here so that contribution is easier for everybody. At some point it could be converted in a blog post. (or a blog post can summarise and edit the content of this thread).

#4

It seems possible for admins to turn posts into “Wiki posts” in Discourse:

It may make sense for a post like this, where several people could make incremental contributions.

1 Like
#5

I’ve made a wiki out of the original post. Thanks @jeroen!

#6

What I currently understand of the locus system is the following:

When a new locus is inserted (enable Tools->Linking tool, then Link->New locus), a locus element is inserted in the document. This locus has a unique id and a content tree, which can be manipulated.

You can see a list of loci by doing Link->Extract->Loci (created using tree-search on (buffer-tree)). Although the id is created uniquely, by copying these elements different loci with the same id can exist. Their contents need not be identical. Given a locus element, (locus-id t) will give the locus id as a string, where t is a TeXmacs tree.

If you have the id of a locus, you can get the tree of the corresponding element with (id->loci "...."), taking the id string as argument. Note that this really a sub-tree of the document tree, so it is useful to find, for example, certain elements containing a locus using with-innermost or tree-up and the like. The contents of the locus can be had with (id->trees "....").

Contents can also be manipulated with locus-set, e.g.

(locus-set "+nWR9oal1xAc6vbB" '(math (frac "1" "6")))

This command sets the contents of all loci with the given id.

There are more locus commands (locus-link-types, locus-insert-link, locus-link-follow, etc.), but I haven’t yet worked out how they function.

1 Like
What is Link mode?
#7

locus macro usually has two structure. This macro needs a [id-text] and a [display-text], then rendered as a link shown as [display-text].
.
The first structure indicates a link to somewhere of document, maybe includes some hover text. [href-text] is destination of this link, which has a special format.

<locus/>
  <id|[id-text]>
<locus|>
  <link\>
    hyperlink
  <link|>
    <id|[id-text]>
  <link|>
    <url|[href-text]>
  <link/>
<locus|>
  [display-text]
<locus\>

The second structure shows here:

<locus/>
  <id|[id-text]>
<locus|>
  <observer|[id-text]|mirror-notify>
<locus|>
  <hidden/>
    <extern|[extern-macro]|[extern-args]>
  <hidden\>
<locus|>
  [display-text]
<locus\>
3 Likes
#8

The Linking tool remains a bit of a mystery to me, so I had another look at the source code. Now I finally understand how to create some of the links described by @jingkaimori above :slight_smile:

  • Insert a locus with Link->New locus
  • Set the locus as the source: Link->Source (while inside the source locus)
  • Insert a second locus elsewhere.
  • Set the locus as the target: Link->Target->Locus
  • Create a link with Link->Create link->hyperlink

Note:

  • There can be multiple links in one locus, so the element can start with an <id|[id-text]>, then have multiple <link> elements, and end with a [display-text].
  • When inside a locus with links, links can be deleted via Link->Delete link
  • There seem to be some serious bugs. I experienced several crashed while experimenting with links.
  • The Link->Extract->Constellation tool looks very interesting!
2 Likes
#9

There is a doc-authors macro definition, and section 13.5 of TJW introduces it, but this macro can be neither inserted from gui, nor recognized as metadata of document like doc-author in several situations. So is it suggested to use this macro?

#10

I don’t think the doc-authors macro is for human input. Multiple authors lines up as:

<doc-data|<doc-title|a title>|<doc-author|...>|<doc-author|...>>

The doc-data macro then passes arguments to doc-data scheme function (packages/header/title-base.ts), which invokes doc-authors macro to render them in a prescribed way(progs/database/title-markup.scm:L143).

#11

Yes, this macro is not for user input. So is it necessary to change its name to reduce misleading to developers?

#12

Is there any more understanding of the Linking features of TeXmacs? I think we should write a more extensive account with some useful examples.