documentation improvements

[bdarcus]

First, this looks great!

But I did run into problems being able to run the example file.

1. I found I got an error about a missing "inspect" package.
2. I installed that using luarocks, and still got the error.
3. I then symlinked it to the texmfhome dir, and that ran, but ...
4. I got an error about a missing locale file.

After I sorted that all out, I did get it to run, with reasonable output, but got an error about an unsupported "en-US" locale.

[zepinglee]

Do you have an up-to-date installation of TeX Live 2022? This package (https://ctan.org/pkg/citation-style-language) is already a part of it and the example is expected to run successfully out-of-the-box with latexmk -lualatex example.tex.

1. I found I got an error about a missing "inspect" package.

I check the dependency and find the inspect is only required for debugging. It should be removed in pure running procedures.

2. I installed that using luarocks, and still got the error.

The texlua interpreter doesn't lookup into the packages installed by luarocks by default.

3. I then symlinked it to the texmfhome dir, and that ran, but ...

The texmf structure of this package is different from its code repository. You may need make install to install it to TEXMFHOME which is usually ~/texmf or ~/Library/texmf. The file structure should be as follows (with some similar files omitted). The locales and styles modules need be initialized with git submodule update --init before the installation.

~/Library/texmf
├── scripts
│   └── citation-style-language
│       ├── citeproc
│       ├── citeproc-bib.lua
│       ├── citeproc-element.lua
│       ├── citeproc-engine.lua
│       ├── citeproc-formats.lua
│       ├── citeproc-node-choose.lua
│       ├── citeproc-node-date.lua
│       ├── citeproc-node-group.lua
│       ├── citeproc-node-label.lua
│       ├── citeproc-node-layout.lua
│       ├── citeproc-node-locale.lua
│       ├── citeproc-node-names.lua
│       ├── citeproc-node-number.lua
│       ├── citeproc-node-sort.lua
│       ├── citeproc-node-style.lua
│       ├── citeproc-node-text.lua
│       ├── citeproc-nodes.lua
│       ├── citeproc-richtext.lua
│       ├── citeproc-util.lua
│       ├── citeproc.lua
│       ├── csl-core.lua
│       └── csl.lua
└── tex
    └── latex
        └── citation-style-language
            ├── citation-style-language.sty
            ├── citeproc-bib-data.json
            ├── locales
            │   ├── csl-locales-af-ZA.xml
            │   ├── csl-locales-ar.xml
            │   ├──     .
            │   ├──     .
            │   ├──     .
            │   ├── csl-locales-en-GB.xml
            │   ├── csl-locales-en-US.xml
            │   ├──     .
            │   ├──     .
            │   ├──     .
            │   ├── csl-locales-zh-CN.xml
            │   └── csl-locales-zh-TW.xml
            └── styles
                ├── american-chemical-society.csl
                ├── american-medical-association.csl
                ├──     .
                ├──     .
                ├──     .
                ├── nature.csl
                └── vancouver.csl

[bdarcus]

Do you have an up-to-date installation of TeX Live 2022?

I use fedora to handle texlive updating. It's currently at 2021, but looks like 2022 is coming soon; likely with the release of F36 on Tuesday.

This package (https://ctan.org/pkg/citation-style-language) is already a part of it and the example is expected to run successfully out-of-the-box with latexmk -lualatex example.tex.

Oh good. This may be moot then.

You may want to mention that on the README?

You may need make install to install it to TEXMFHOME.

I should have mentioned: I did that.

[zepinglee]

You may want to mention that on the README?

Yes, I'll add some notes about the TeX Live versions.

After I sorted that all out, I did get it to run, with reasonable output, but got an error about an unsupported "en-US" locale.

I've just installed the TeX Live 2021 version and reproduced all you described. The “unsupported en-US” message is misleading and it's actually caused by the absence of this language in lua-uca, the library required for sorting. Since en-US is the default language, this warning should not occur.