Creating a bibliography style

[schroedingers_possum]

Hello Everyone,

preamble

This is a not yet polished guide on how I customized the bibliography style to show hyperlinks to the DOIs of articles, which I want for an article that I’m writing. I will continue to update it if I figure out something new, or if something is pointed out to me in the comments below. My hope is that, maybe, this can help someone, and perhaps together we can improve the TeXmacs help article on it to make it a bit easier for beginners.

I am not going to enter into the details of how to program the bibliography style with Scheme, but I am only giving a step by step guide on this one example. This being said, you should be able to easily extend this for deeper and/or different bibliographies with some knowledge of BibTex and Scheme.

There is already some guidance on how to do this under Help->Scheme extensions->Writing TeXmacs bibliography files, but I still found myself to be pretty overwhelmed with the task, and it took me a while to figure it out despite. Nonetheless, the TeXmacs help article is a pretty good reference and if you are interested in/required to customize the bibliography style, I definitely recommend going through it. There is also this forum thread with additional discussion and info.

Guide

I think that it is a good idea to first choose a style that is close to what you have in mind, and make a derivative of that one. In my case, tm-elsart-num was a good starting point, since it orders the sources in the order that they appear in the text and cites numerically.

Once you have as style that you like, we need to find the Scheme files, where the code for the bibliographies are located. These are in the TeXmacs data directory. On Linux and MacOS, this is usually located at /home/$USER/.TeXmacs/. On Windows the path should be %appdata%/TeXmacs.

If for some reason it isn’t there, you can download this TeXmacs file, open it in TeXmacs and follow the instructions in the file.

Navigate to the TeXmacs path and go to progs. If there is no folder named bibtex here, create an empty folder and name it bibtex.

Download the Style that is closest to what you from the TeXmacs Git Repository here and copy it to this folder ($TEXMACS_HOME_PATH/progs/bibtex/). Rename the stylefile with a good name for your modified style (like julius-link-elsart-num.scm to make it easy to remember what your style is in the future).

Open the file in your text editor of choice. Use Replace (often ctrl+h) to replace the original name of the file, in our example elsart-num with the name of your style, which should be the same as the file name you have chosen for your style file. Replace all occurrences in the document.

notice that the document julius-link-elsart-num.scm, which looked like this at the top of the document … ↓

14: (texmacs-module (bibtex elsart-num)
15:  (:use (bibtex bib-utils) (bibtex plain)))

… should now look like this ↓

14: (texmacs-module (bibtex julius-link-elsart-num)
15:  (:use (bibtex bib-utils) (bibtex plain)))

If you scroll down, you will see the definitions for the different parts of the BibTeX bibliography. They are Scheme function applications like (tm-define (bib-format-name x), etc.

Below the other tags, append the following (in my case at line 100):

;; Added function to format URL field
(define (bib-format-url x)
  (let* ((u (bib-field x "url")))
    (if (bib-null? u) "" `(concat "url: " ,u))))

Then add the url field to the article entry definition just below: So look for this part in the file… ↓

(tm-define (bib-format-article n x)
  (:mode bib-julius-link-elsart-num?)
  `(concat ,(bib-format-bibitem n x)
	   ,(bib-label (list-ref x 2))
	   ,(bib-new-block
	     (bib-new-sentence
	      `(,(bib-format-author x)
		,(bib-format-field-Locase x "title")
		,@(if (bib-empty? x "crossref")
		      `(,(bib-format-vol-num-pages x))
		      `((concat ,(bib-translate "in ")
				(cite ,(bib-field x "crossref")))
			,(bib-format-pages x)))
		,(bib-format-note x))))))

… and add the last line below ↓

(tm-define (bib-format-article n x)
  (:mode bib-julius-link-elsart-num?)
  `(concat ,(bib-format-bibitem n x)
	   ,(bib-label (list-ref x 2))
	   ,(bib-new-block
	     (bib-new-sentence
	      `(,(bib-format-author x)
		,(bib-format-field-Locase x "title")
		,@(if (bib-empty? x "crossref")
		      `(,(bib-format-vol-num-pages x))
		      `((concat ,(bib-translate "in ")
				(cite ,(bib-field x "crossref")))
			,(bib-format-pages x)))
		,(bib-format-note x)
        ,(bib-format-url x))))))

Do this for the other entry types on which you want the urls to show up on.

If you have TeXmacs opened, then restart it now so that it can reload the bibliographies.
Then open the document and head down to the bibliography.
Click on the bibliography, click on the current style:

And click on Other .... It will show a Pop-Up, where you can enter the name of your style, prefixed with “tm-”. For example, tm-julius-link-elsart-num. Then click on “ok”. Now rebuild the current buffer (either click on the button or do crtl+shift+R). The sources should now show up.

Did everything work out?

[pireddag]

I will have more time to look at your post next week, this said: would you consider posting the same in TeXmacs blog at https://texmacs.github.io/notes/docs/main.html ?

Instructions on how to post are at https://github.com/texmacs/notes
Or you could send the post in TeXmacs format to @mgubi and he will publish it on the blog for you.

I think the blog and all TeXmacs users would benefit strongly from a how-to section.

Moreover posts in the forum slide away as new posts are published and so disappear from the awareness of users. There is a nice wiki how-to post which you can see only if you are not logged in, for example: usually the fact that it exists slips away from my mind. On the opposite, posts remain prominent on the blog.

This would not exclude publishing the same under a Wikipedia TeXmacs how-to wikibook (which yet needs to be started )

[schroedingers_possum]

I wanted to collect some feedback before going further, since making changes is easier in the forum

[pireddag]

Please give me some time to read the post and try the code

[pireddag]

@schroedingers_possum I wrote you through the messaging system of the forum.

[schroedingers_possum]

@pireddag thanks for the message
I rewrote a part of the preamble, I hope that this is a bit clearer than before.

[dash003]

Hi @schroedingers_possum,

@pireddag pointed me to your post (thanks for that!).

I did not try your walkthrough, but rather hacked the pieces together for an APA 7 style bibliography file. It somehow works and implements a few ideas like websites, misc, journal, report. But it still has some bugs regarding year and styling etc. Implementing the full APA 7 specification is a Herculean task, I’m not up to it…

What I’m still missing is a proper modification of the cite command, since it still uses numbers instead of the APA required format (author, year). I’m not sure where the file is (I’m on macos) and to what extent it needs to be modified to work with my bibliography file.

See the screenshots below for reference and my current state:

It’s still very buggy, and I’m not sure how much more time I can spend on a proper (lightweight) implementation. However, with further guidance I will try to at least (hopefully) get it to an acceptable state.

Cheers

P.S. Where should I put my .scm file for reference?

[mgubi]

We are collecting Source code / examples /temaplate for TeXmacs in https://github.com/texmacs/tm-forge

Pull requests are welcome.

[mgubi]

I agree with @pireddag that this would make a great article for https://texmacs.github.io/notes , even if it is in a preliminary state, would be good. We can improve it further later, also the users can provide feedback with the issues or PR requests mechanisms of GitHub, or here.

[pireddag]

What I’m still missing is a proper modification of the cite command

I looked at the bibliography style file abstract.scm, that cites by key, and there I found the function bib-format-bibitem with two input arguments. The x input argument is the bibliography entry with all its fields (I saw it inserting a display command). I think that by writing a custom bib-format-bibitem one can obtain the format of the citation one desires, I expect that it will be the same in both bibliography and citations.

I would keep the mode condition in bib-format-bibitem (adapting its name), and therefore a new one needs to be added to TeXmacs as well; I do not see immediately why that function might be called with the custom definition in a different context than formatting the citations with the style where it is defined, but if the mode condition is there, let us copy it

As an example, for the custom bibliography style,

(texmacs-modes
 (bib-custom% (bib-mode? "custom") bib-plain%))

[schroedingers_possum]

Hi @dash003,

the screenshot looks quite promising

I accidentally deleted the part in the tutorial last time that I editied, sorry about that . On your mac the file should go to /home/$USER/.TeXmacs/progs/bibtex/, where you will probably need to create a folder there (either navigate to /home/$USER/.TeXmacs/progs/ and create a new empty folder named bibtex, or run the following commands:

cd /home/$USER/.TeXmacs/progs/
mkdir bibtex

After restarting TeXmacs it should be possible to use the style.

For sharing the file that you are working on, I created a pull request for tm-forge to have a folder where bibliography styles can be put.

[pireddag]

I created a pull request for tm-forge to have a folder where bibliography styles can be put.

Would it make sense to place that folder one level up? At the same level of the styles folder.

[dash003]

To clarify, my bib file is not 100% functional. It works for basic .bib files, but there are so many exceptions and special cases with regard to APA 7 that I’m currently considering whether I really want to extend it or just make it work for my personal purposes. I don’t mind sharing the buggy version I currently have, although I don’t think it’s at a stage where it deserves to be pulled into the tm-forge project

I might add that, depending on how much time it takes, I might not finish this - writing the code is (to be honest) quite frustrating Let me know if you’re still interested.

I put my bibstyle file in /Applications/TeXmacs.app/Contents/Resources/share/TeXmacs/progs/bibtex
where I put the other default files. I guess this makes it “global” instead of putting it in ~/$USER…
But I don’t mind either.

What I’m looking for is where the code for the \cite command is.
When I use \cite I just get [?] Another thing is that when I use ieee and cite, then switch to my own APA, the reference number is there, after updating the document a few times it goes back to [?] I guess TM needs some time to clear the cache?

[pireddag]

What I’m looking for is where the code for the \cite command is.

I think it is the function bib-format-bibitem, which you have to provide either through making the module for your style dependent on other modules or writing a new one for your style. In the style I looked at, abstract.scm, it is redefined conditionally (:mode form).

[mgubi]

I think it is ok to provide some examples, and also something other people could improve while using it. Maybe adding a warning. Anyway open source software should be used on a “your mileage may vary” policy. If somebody needs some polished thing they can always support a developer to provide something fitting to their needs.

[pireddag]

I think it is ok to provide some examples, and also something other people could improve while using it. Maybe adding a warning.

I think so too. I did not check it package by package, this said I think that the very nice TeX/LaTeX packages like siunitx, chemfig, tcolorbox or TikZ have been developed after other less complex packages.

[dash003]

Thanks for all the feedback!
I have created a pull request on tm-forge with my style file.

I hope this will be useful for someone to extend it in a meaningful and functional way so that it can really be used by the community in the future.

[schroedingers_possum]

Hey, it has been a while since I’ve updated this.
For some reason I’m no longer able to edit the guide in the forum, so I’ll make any future changes directly to the entry on TeXmacs notes. Once again thank you very much especially to pireddag and mgubi for the feedback and help.