Added documentation for extra file columns

[Tridecatrix]

Addresses issue #435. Documents the extra file column option in entry tables, as described in https://discourse.jabref.org/t/pdf-column-in-entry-table/3696/4?u=siedlerch. Includes screenshots.

Have confirmed that the feature demonstrated in this documentation is valid as of JabRef 5.15 (the version I was testing on).

Some questions I have:

• I noticed while testing that unlike for the normal linked files column, it does not open the file when clicking on the icon in the entry table for extra file columns. I will verify whether this behavior persists in the latest main version of JabRef on the repo, but otherwise I believe an issue should be made to fix it?
• I was also unable to drag columns and reorder them from the Preferences menu directly, even though the comment thread I was following when making the guide (https://discourse.jabref.org/t/pdf-column-in-entry-table/3696/4?u=siedlerchr) indicates it should be possible to do so. I will also verify this behavior in the latest version, and think it requires an issue if it exists.

[Tridecatrix]

By the way, a question:

I noticed that my lint workflow had failed (my mistake by the way) and went to try and run the workflow myself after my second commit. The way I decided to do this was to run the workflows on my local fork through the Actions tab using the online Github CI (since my docker knowledge is somewhat poor and I couldn't be bothered setting up act lol; it was the quickest solution for me. Considering actually updating the dev help page at https://github.com/JabRef/user-documentation/blob/main/en/contributing/how-to-improve-the-help-page.md to indicate this option to others).

Well anyway when running the workflows, I found that the Markdown links workflow had failed:

The error output of the workflow actually complains about a lot more links than I expected, including ones I didn't touch at all. It claims a lot of dead links exist. Some of these are valid; I couldn't follow the link to https://github.com/JabRef/jabref/blob/main/LICENSE.md for example, returns 404. But then it also complains about dead links to images which do actually exist, such as "findunlinkedfiles-08-entry-editor.png". Maintainers dont seem to have run the markdown links workflow on other PRs either. Just out of curiosity: is the workflow just raising false alarms and the workflow itself should be fixed for this check to be meaningful, or are there a bunch of dead links in the documentation? Or both?? Wondered if I should create an issue for it lol.

[koppor]

Meta: We are discussing a very different thing here. Let's hope, this does not disctract the others thinking of your initial questions. I don't have time currently to really think of your questions, but ohter JabRef users and maintainers should be able to answer whether a click on a file icon works and can go back and forth with you with a minimal example etc.

The error output of the workflow actually complains about a lot more links than I expected, including ones I didn't touch at all.

That's normal. Link-checking is hell..

Options are

• https://github.com/TechWiz-3/linksafe (once very active)
• https://github.com/lycheeverse/lychee/ / https://github.com/lycheeverse/lychee-action (which we use in JabRef)
• https://github.com/UmbrellaDocs/linkspector
• https://github.com/gaurav-nelson/github-action-markdown-link-check (which we use here)
• https://github.com/peter-evans/link-checker
• A list of other alternatives: https://github.com/lycheeverse/lychee/?tab=readme-ov-file#features

A link checker should be able to cope with blocks by GitHub or CloudFlare. It should just report them as warning not as issue. I did not find the time to try all out and configure them properly for GitHub. Maybe Lychee does now. Maybe you can investigate?

I saw once some checkers where the handling of http response codes can be configured. I hate thus configurations, because I think, they are common: All GitHub repositories need proper GitHub and Cloudflare handling; not everyone separate.

https://github.com/JabRef/jabref/blob/main/.github/workflows/check-links.yml is a "good enough" configuration.

@Tridecatrix Can you submit a PR porting https://github.com/JabRef/jabref/blob/main/.github/workflows/check-links.yml and https://github.com/JabRef/jabref/blob/main/.lycheeignore to here? (Refs https://github.com/JabRef/jabref/blob/main/.lycheeignore). Maybe even setup an action where a change of these files in the JabRef repo is synched here using a pull request?

You can also come up with other link checker which is even better?

The current solution has the drawback that it ignores JabRef files (and you already found that our License file was renamed). -- Please fix that link in a seperate PR.

[Tridecatrix]

Hi Koppor,

Thanks for the detailed response. It will be a few days (at least until Monday my time) before I can take a look into the links issue but I can try.

As for the documentation itself that I have added in this PR, any comments or is it ready to merge?

[koppor]

Thanks for the detailed response. It will be a few days (at least until Monday my time) before I can take a look into the links issue but I can try.

Unfortunately, I can only repeat my third sentence of my reply:

I don't have time currently to really think of your questions, but ohter JabRef users and maintainers should be able to answer whether a click on a file icon works and can go back and forth with you with a minimal example etc.

@JabRef/developers Does someone of you have time to dive into this, please?

[calixtus]

The error output of the workflow actually complains about a lot more links than I expected, including ones I didn't touch at all. It claims a lot of dead links exist. Some of these are valid; I couldn't follow the link to https://github.com/JabRef/jabref/blob/main/LICENSE.md for example, returns 404. But then it also complains about dead links to images which do actually exist, such as "findunlinkedfiles-08-entry-editor.png". Maintainers dont seem to have run the markdown links workflow on other PRs either. Just out of curiosity: is the workflow just raising false alarms and the workflow itself should be fixed for this check to be meaningful, or are there a bunch of dead links in the documentation? Or both?? Wondered if I should create an issue for it lol.

Correct link is https://github.com/JabRef/jabref/blob/main/LICENSE (without .md)

About non working images: do they show up in the documentation itself (docs.jabref.org) ?

[koppor]

Please follow the one-sentence-per-line rule. This makes diffing easier.

This sentence is a bit unclear. Please tell the user that <filetype> can be "Markdown", "PNG Image", or other things. The text should be self contained. Remember visually impaired persons so that documents should be accessible. the included image alt text do not contain the list of shown types. Thus, a person with a screen reader has no chance to get the information.

Split up the sentence. Say that after the click, new entries appear as choice at the end of the combo box.

Please also add that one needs to click the plus button right of the field to add.

Moreover, Say that the arrow up and down buttons can be used to move the field more up.

[koppor]

Be clear. Split the first sentence. Start a new one at "e.g.,", but use instead: "For instance, one might store longer comments in an external Markdown file. One wants to show the precense of this Markdown file using an extra column".

With this text, you introduce the running example "Markdown" explicitely.

[koppor]

* I noticed while testing that unlike for the normal linked files column, it does not open the file when clicking on the icon in the entry table for extra file columns. I will verify whether this behavior persists in the latest main version of JabRef on the repo, but otherwise I believe an issue should be made to fix it?

Filed as JabRef/jabref#12005

[koppor]

* I was also unable to drag columns and reorder them from the Preferences menu directly, 

Yeah, this is not possible. You can file a feature wish if you want.

even though the comment thread I was following when making the guide (discourse.jabref.org/t/pdf-column-in-entry-table/3696/4?u=siedlerchr) indicates it should be possible to do so. I will also verify this behavior in the latest version, and think it requires an issue if it exists.

What Christoph meant is drag'n'drop in the main table. If you drag the title of a column, you can reorder it:

[koppor]

@Tridecatrix You could contribute to https://github.com/JabRef/jabref/blob/main/docs/decisions/0011-test-external-links-in-documentation.md, too :) - Risen by JabRef/jabref#11912 (comment).

[Tridecatrix]

Hi @koppor ,
Surprise: I fully intended to stop working but then I saw the changes you requested here and couldn't resist! I hope the rewordings I've made are clearer; I also updated the images a bit.

I made almost all the changes requested except possibly one-sentence-per-line. The thing with that one is that I see other places in the same document with multiple sentences in a single line (i.e. paragraph)? E.g. line 78 and line 82. How strict of a rule is this? Because I think it will take a lot of fixes to fully enforce it if it truly is a rule...

[koppor]

Hi @koppor , Surprise: I fully intended to stop working but then I saw the changes you requested here and couldn't resist! I hope the rewordings I've made are clearer; I also updated the images a bit.

:)

I made almost all the changes requested except possibly one-sentence-per-line. The thing with that one is that I see other places in the same document with multiple sentences in a single line (i.e. paragraph)? E.g. line 78 and line 82. How strict of a rule is this? Because I think it will take a lot of fixes to fully enforce it if it truly is a rule...

It will gradually evolve. - When people start editing with GitBook, it will be destroyed though. We are thinking to switch to Docusaurus though... (Similar to OpenRewrite - openrewrite/rewrite-docs#162)