Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/RolfBremer/in-dexter

Automatically create a handcrafted index in typst.
https://github.com/RolfBremer/in-dexter

typst

Last synced: 6 days ago
JSON representation

Automatically create a handcrafted index in typst.

Awesome Lists containing this project

README 

        
# in-dexter



Automatically create a handcrafted index in [typst](https://typst.app/).

This typst component allows the automatic creation of an Index page with entries

that have been manually marked in the document by its authors. This, in times

of advanced search functionality, seems somewhat outdated, but a handcrafted index

like this allows the authors to point the reader to just the right location in the

document.



⚠️ Typst is in beta and evolving, and this package evolves with it. As a result, no

backward compatibility is guaranteed yet. Also, the package itself is under development

and fine-tuning.



## Table of Contents



* [Usage](#usage)

  * [Importing the Component](#importing-the-component)

  * [Remarks for new version](#remarks-for-new-version)

  * [Marking Entries](#marking-entries)

    * [Generating the index page](#generating-the-index-page)

    * [Brief Sample Document](#brief-sample-document)

    * [Full Sample Document](#full-sample-document)

* [Changelog](#changelog)

  * [v0.6.1](#v061)

  * [v0.6.0](#v060)

  * [v0.5.3](#v053)

  * [v0.5.2](#v052)

  * [v0.5.1](#v051)

  * [v0.5.0](#v050)

  * [v0.4.3](#v043)

  * [v0.4.2](#v042)

  * [v0.4.1](#v041)

  * [v0.4.0](#v040)

  * [v0.3.2](#v032)

  * [v0.3.1](#v031)

  * [v0.3.0](#v030)

  * [v0.2.0](#v020)

  * [v0.1.0](#v010)

  * [v0.0.6](#v006)

  * [v0.0.5](#v005)

  * [v0.0.4](#v004)

  * [v0.0.3](#v003)

  * [v0.0.2](#v002)



## Usage



## Importing the Component



To use the index functionality, the component must be available. This

can be achieved by importing the package `in-dexter` into the project:



Add the following code to the head of the document file(s)

that want to use the index:



```typ

  #import "@preview/in-dexter:0.6.1": *

```



Alternatively it can be loaded from the file, if you have it copied into your project.



```typ

  #import "in-dexter.typ": *

```



## Remarks for new version



In previous versions (before 0.0.6) of in-dexter, it was required to hide the index

entries with a show rule. This is not required anymore.



## Marking Entries



To mark a word to be included in the index, a simple function can be used. In the

following sample code, the word "elit" is marked to be included into the index.



```typ

= Sample Text

Lorem ipsum dolor sit amet, consectetur adipiscing #index[elit], sed do eiusmod tempor

incididunt ut labore et dolore.

```



Nested entries can be created - the following would create an entry `adipiscing` with sub entry

`elit`.



```typ

= Sample Text

Lorem ipsum dolor sit amet, consectetur adipiscing elit#index("adipiscing", "elit"), sed do eiusmod

tempor incididunt ut labore et dolore.

```



The marking, by default, is invisible in the resulting text, while the marked word

will still be visible. With the marking in place, the index component knows about

the word, as well as its location in the document.



## Generating the Index Page



The index page can be generated by the following function:



```typ

= Index

#columns(3)[

  #make-index(title: none)

]

```



This sample uses the optional title, outline, and use-page-counter parameters:



```typ

#make-index(title: [Index], outlined: true, use-page-counter: true)

```



The `make-index()` function takes three optional arguments: `title`, `outlined`, and `use-page-counter`.



* `title` adds a title (with `heading`) and

* `outlined` is `false` by default and is passed to the heading function

* `use-page-counter` is `false` by default. If set to `true` it will use `counter(page).display()` for the page

    number text in the index instead of the absolute page position (the absolute position is still

    used for the actual link target)



If no title is given the heading should never appear in the layout.

Note: The heading is (currently) not numbered.



The first sample emits the index in three columns.

Note: The actual appearance depends on your template or other settings of your document.



You can find a preview image of the resulting page

on [in-dexter´s GitHub repository](https://github.com/RolfBremer/in-dexter).



You may have noticed that some page numbers are displayed as bold. These are index entries

which are marked as "main" entries. Such entries are meant to be the most important for

the given entry. They can be marked as follows:



```typ

#index(fmt: strong, [Willkommen])

```



or you can use the predefined semantically helper function



```typ

#index-main[Willkommen]

```



### Brief Sample Document



This is a very brief sample to demonstrate how in-dexter can be used. The next chapter

contains a more fleshed out sample.



```typ

#import "@preview/in-dexter:0.6.1": *



= My Sample Document with `in-dexter`



In this document the usage of the `in-dexter` package is demonstrated to create

a hand picked #index[Hand Picked] index. This sample #index-main[Sample]

document #index[Document] is quite short, and so is its index.



= Index



This section contains the generated Index.



#make-index()

```



### Full Sample Document



```typ

#import "@preview/in-dexter:0.6.1": *



#let index-main(..args) = index(fmt: strong, ..args)



// Document settings

#set page("a5")

#set text(font: ("Arial", "Trebuchet MS"), size: 12pt)



= My Sample Document with `in-dexter`



In this document #index[Document] the usage of the `in-dexter` package #index[Package]

is demonstrated to create a hand picked index #index-main[Index]. This sample document

is quite short, and so is its index. So to fill this sample with some real text,

let´s elaborate on some aspects of a hand picked #index[Hand Picked] index. So, "hand

picked" means, the entries #index[Entries] in the index are carefully chosen by the

author(s) of the document to point the reader, who is interested in a specific topic

within the documents domain #index[Domain], to the right spot #index[Spot]. Thats, how

it should be; and it is quite different to what is done in this sample text, where the

objective #index-main[Objective] was to put many different index markers

#index[Markers] into a small text, because a sample should be as brief as possible,

while providing enough substance #index[Substance] to demo the subject

#index[Subject]. The resulting index in this demo is somewhat pointless

#index[Pointless], because all entries are pointing to few different pages

#index[Pages], due to the fact that the demo text only has few pages #index[Page].

That is also the reason for what we chose the DIN A5 #index[DIN A5] format, and we

also continue with some remarks #index[Remarks] on the next page.



== Some more demo content without deeper meaning



#lorem(50) #index[Lorem]



#pagebreak()



== Remarks



Here are some more remarks #index-main[Remarks] to have some content on a second page, what

is a precondition #index[Precondition] to demo that Index #index[Index] entries

#index[Entries] may point to multiple pages.



= Index



This section #index[Section] contains the generated Index #index[Index], in a nice

two-column-layout.



#set text(size: 10pt)

#columns(2)[

    #make-index()

]

```



The following image shows a generated index page of another document, with additional

formatting for headers applied.



![Sample for a generated index page.](gallery/SampleIndex.png)



More usage samples are shown in the document `sample-usage.typ` on

[in-dexter´s GitHub](https://github.com/RolfBremer/in-dexter).



A more complex sample PDF is available there as well.



## Changelog



### v0.6.1



* Configurable range delimiter. Defaults to em-dash now.



### v0.6.0



* Support for Ranges and Continuations (range references, f. ff.).

* Fix: Consolidate multiple references to the same page.



### v0.5.3



* Fix error in typst.toml file.

* Add a sample for raw display.



### v0.5.2



* Fix a bug with bang notation.

* Add compiler version to toml file.



### v0.5.1



* Migrate deprecated locate to context.



### v0.5.0



* Support page numbering formats (i.e. roman), when `use-page-counter` is set to

  true. Thanks to @ThePuzzlemaker!



### v0.4.3



* Suppress extra space character emitted by the `index()` function.

* Fix a bug where math formulas are not displayed.

* Introduce `apply-casing` parameter to `index()` to suppress entry-casing for individual

  entries.



### v0.4.2



* Improve internal method `as-text` to be more robust.

* tidy up sample-usage.typ.



### v0.4.1



* Bug fixed: Fix a bug where an index entry with same name as a group hides the group.

* Fixed typos in the sample-usage document.



### v0.4.0



* Support for a `display` parameter for entries. This allows the usage of complex

  content, like math expressions in the index. (based on suggestions by @lukasjuhrich)

* Also support a tuple value for display and key parameters of the entry.

* Improve internal robustness and fix some errors in the sample document.



### v0.3.2



* Fix initial parsing and returning fist letter (thanks to @lukasjuhrich, #14)



### v0.3.1



* Fix handling of trailing or multiple spaces and crlf in index entries.



### v0.3.0



* Support multiple named indexes. Also allow the generation of

  combined index pages.

* Support for LaTeX index group syntax (`#index("Group1!Group2@Entry"`).

* Support for advanced case handling for the entries in the index. Note: The new default

  ist to ignore the casing for the sorting of the entries. The behavior can be changed by

  providing a `sort-order()` function to the `make-index` function.

* The casing for the index entry can also be altered by providing a `entry-casing()`

  function to the `make-index` function. So it is possible that all entries have an

  uppercase first letter (which is also the new default!).



### v0.2.0



* Allow index to respect unnumbered physical pages at the start of the

  document (Thanks to @jewelpit). See "Skipping physical pages" in the

  sample-usage document.



### v0.1.0



* big refactor (by @epsilonhalbe).

* changing "marker classes" to support direct format

  function `fmt: content -> content` e.g. `index(fmt: strong, [entry])`.

* Implemented:

  * nested entries.

  * custom initials + custom sorting.



### v0.0.6



* Change internal index marker to use metadata instead of figures. This

  allows a cleaner implementation and does not require a show rule to hide

  the marker-figure anymore.

* This version requires Typst 0.8.0 due to the use of metadata().

* Consolidated the `PackageReadme.md` into a single `README.md`.



### v0.0.5



* Address change in `figure.caption` in typst (commit: 976abdf ).



### v0.0.4



* Add title and outline arguments to #make-index() by @sbatial in #4



### v0.0.3



* Breaking: Renamed the main file from `index.typ` to `in-dexter.typ` to match package.

* Added a Changelog to this README.

* Introduced a brief and a full sample code to this README.

* Added support for package manager in Typst.



### v.0.0.2



* Moved version to GitHub.