First draft for en/getting-started.md #297

matthiasgeiger · 2020-09-01T12:37:32Z

Hello together,
as agreed here some contents for the "getting-started" page ;-)

Best regards,
Matthias

tobiasdiez · 2020-09-01T21:49:20Z

I like this a lot! Thanks Matthias!

Only one remark from my side: we recently renamed the bibtexkey to citationkey. This rename should also be in 5.1 if I'm not mistaken.

matthiasgeiger · 2020-09-02T06:34:53Z

Not in 5.1:

Should I change it anyway?

Siedlerchr · 2020-09-02T06:41:40Z

@matthiasgeiger At least in all dialogs and preferences we renamed it.

mlep · 2020-09-02T13:45:30Z

The obvious (but small) problem with naming the field bibtexkey is that it does not make sense for biblatex database.
So, a biblatexkey for biblatex files?
And both bibtexkey and biblatexkey are citation keys?
😉

Looking at the vocabulary used in official sources for BibTeX and biblatex (i.e. their documentation and log output):

First, nowhere I could find bibtexkey 😮

Second, what I found:

BibTeX

doc

"The database key of the entry being cross referenced."

output

Warning--I didn't find a database entry for "test"
Repeated entry ---line 426 of file References.bib

biblatex

doc

You may also use the ‘citekey’ or ‘entrykey‘ pseudo-fields to specify the citation/entry key as part of the label.
Sort by entry key.
with any of the specified citation keys
With BibTeX datasources, you may specify the pseudo-field entrykey for
fieldsource which is the citation key of the entry. With biblatexml the
entrykey** is a normal

output

[286] Biber.pm:943> INFO - Found 1 citekeys in bib section 3
[9294] Utils.pm:304> WARN - Duplicate entry key: 'Hahmid99' in file 'biblio.bib', skipping ...

So, nothing uniform...

An (obvious) proposition:
Citation key for plain language and citekey for the field name?
(whatever the file type 😉)

koppor · 2020-09-02T18:57:49Z

The renaming took place in JabRef/jabref#6545.

koppor · 2020-09-02T18:59:30Z

"Citation Key" is no field name.

@article{KEY,
  title = {thing}

We denote the KEY in the above example. Not a certain field.

mlep · 2020-09-02T20:00:11Z

@koppor In the JabRef interface, the bibtexkey "stuff" looks like a field. 😕

koppor · 2020-09-02T22:37:13Z

@mlep This refs JabRef/jabref#6856. Think, we have no chance than rebuilding the entry editor (again).

tobiasdiez · 2020-09-04T21:59:58Z

The perfect solution would probably be to keep it at bibtexkey for now, and then switch to citationkey once 5.2 is released. To make life easier for us, I would say we already can use citation key consistently.
Could you please update the screenshots with the branch JabRef/jabref#6875. There "bibtexkey" is replaced by citation key.

matthiasgeiger · 2020-09-06T07:39:25Z

Screenshots updated in Gitbooks with c142ac7 directly on master - text further adjusted in 5dde449 in this PR.

Siedlerchr · 2020-09-06T13:58:33Z

en/getting-started.md

+![Update information from web](.gitbook/assets/getting-started-entry-editor-update-from-web.png)
+
+{% hint style="info" %}
+The found information is most accurate if an identifier like a "DOI" or "ISBN" is maintained. If you already know such an unique identifier, this can also be already the starting point to create a new entry without manual entering any information by using the "create from ID" feature in the Create entry dialog. For more information see: [Collect](https://docs.jabref.org/collect) > ["Add entry using an ID"](https://docs.jabref.org/collect/add-entry-using-an-id)


Maybe add a hint that you can paste DOIs direclty on the main table?

Siedlerchr

In general looks good to me, just some little additions and some typo fixes

en/getting-started.md

Siedlerchr · 2020-09-06T14:14:16Z

en/getting-started.md

+Here you can either attach a file manually, search for an already existing local file matching the bibtexkey pattern, or trying to automatically download a matching full text from the web.
+
+{% hint style="info" %}
+In order to use the automated feature, it is necessary to set-up a file directory first. To do so, please go to "Options" > "Preferences", go to "File" section and select there an existing folder as the "Main file directory":


Suggested change

In order to use the automated feature, it is necessary to set-up a file directory first. To do so, please go to "Options" > "Preferences", go to "File" section and select there an existing folder as the "Main file directory":

In order to use the automated feature, it is necessary to set-up a file directory. The file directory can either be global, local to a user, or specific for a library. See the help on [Override file directories](https://docs.jabref.org/setup/databaseproperties#override-default-file-directories) for details.

For beginners, a main file directory is the most simple setup. It can be set in "Options" -> "Preferences" -> "File"

The default behavior is that JabRef looks for files relative to the bib file, so I would describe this in the getting started section, an then point them to the "Override file directories" section if they want to change that.

If we need to point users to the preferences in "getting started", then we should change the default preferences in my opinion.

Unfortunately, this is not the case - I actually reset the settings before creating the screenshots - and without and change in the settings the following dialog appears:

Default Prefs setting:

Yep. That's a bug which was somehow introduced in 5.1. No idea how it came.

Siedlerchr · 2020-09-06T14:14:56Z

en/getting-started.md

+![Setting up the main file directory](.gitbook/assets/getting-started-preferences.png)
+{% endhint %}
+
+To test the automatic download of full texts you can click on the "Get full-text" icon next to the file field, or choose "Lookup" -> "Search full text documents online" from the menu. As soon as a full-text is found, the file will be stored in the local file directory and linked to the entry:


Suggested change

To test the automatic download of full texts you can click on the "Get full-text" icon next to the file field, or choose "Lookup" -> "Search full text documents online" from the menu. As soon as a full-text is found, the file will be stored in the local file directory and linked to the entry:

To test the automatic download of full texts you can click on the "Get full-text" icon next to the file field, or choose "Lookup" -> "Search full text documents online" from the menu. As soon as a full-text is found, the file will be stored in the previous defined file directory and linked to the entry:

en/getting-started.md

Siedlerchr · 2020-09-06T14:17:00Z

en/getting-started.md

+If you want to search for other references, it is also possible to directly trigger a search in many of the most common bibliographic databases. To start a search just us the "Web Search" feature of JabRef:
+First select one of the existing data sources, enter a search term and click on "search":
+
+The search results will be shown in an window where you can select all the search hits to be added to your library.


Suggested change

The search results will be shown in an window where you can select all the search hits to be added to your library.

The search results will be shown in an window where you can select all the search hits to be added to your library.

You also have the option to directly download the fulltext document (if avaiable and possible).

That's not relevant for a getting started in my opinion

I was referring to the dialog, that it has an option to download the ffull text .

tobiasdiez

I like it a lot! It's very readable and gives the most important information without going into too much detail.

tobiasdiez · 2020-09-06T15:19:13Z

en/getting-started.md

+
+## Creation of a new library
+
+A "library" is the main file that saves all the information about your collection of references. The storage format of the file is text-based in the Bibtex standard.


I would move this information about bibtex to https://docs.jabref.org/cite/bibtex-and-biblatex. It's not utterly important for a new user how JabRef saves his information (except when he starts to cite papers in tex).

As this is for me still one of the essential aspects of JabRef I would keep it ;-)

en/getting-started.md

tobiasdiez · 2020-09-06T15:26:01Z

en/getting-started.md

+Here you can either attach a file manually, search for an already existing local file matching the bibtexkey pattern, or trying to automatically download a matching full text from the web.
+
+{% hint style="info" %}
+In order to use the automated feature, it is necessary to set-up a file directory first. To do so, please go to "Options" > "Preferences", go to "File" section and select there an existing folder as the "Main file directory":


The default behavior is that JabRef looks for files relative to the bib file, so I would describe this in the getting started section, an then point them to the "Override file directories" section if they want to change that.

If we need to point users to the preferences in "getting started", then we should change the default preferences in my opinion.

tobiasdiez · 2020-09-06T15:27:24Z

en/getting-started.md

+If you want to search for other references, it is also possible to directly trigger a search in many of the most common bibliographic databases. To start a search just us the "Web Search" feature of JabRef:
+First select one of the existing data sources, enter a search term and click on "search":
+
+The search results will be shown in an window where you can select all the search hits to be added to your library.


That's not relevant for a getting started in my opinion

en/getting-started.md

tobiasdiez · 2020-09-06T21:23:32Z

Looks good to me! Thanks again.

Tests fail for reasons not relevant to this PR.

matthiasgeiger force-pushed the getting-started branch from b578046 to da2e231 Compare September 1, 2020 18:37

matthiasgeiger added 5 commits September 1, 2020 21:22

First draft for en/getting-started.md

07921cf

Some more content

484bbc8

Adding screenshots

f3b8348

fix path to screenshots

0575a93

additional screenshots

981461d

matthiasgeiger force-pushed the getting-started branch from 44d334e to 981461d Compare September 1, 2020 19:23

matthiasgeiger added 2 commits September 1, 2020 21:27

fix linter findings

8617975

minor fixes

caa77cf

matthiasgeiger marked this pull request as ready for review September 1, 2020 19:37

matthiasgeiger requested a review from koppor September 1, 2020 19:37

formulating text-format hint; mentioning citationkey

621b69c

further adaptions regarding citationkey

5dde449

Siedlerchr reviewed Sep 6, 2020

View reviewed changes

Siedlerchr approved these changes Sep 6, 2020

View reviewed changes

tobiasdiez requested changes Sep 6, 2020

View reviewed changes

matthiasgeiger added 2 commits September 6, 2020 19:43

requested changes

3b0337a

... empty line

758e3d2

tobiasdiez merged commit c6b8567 into master Sep 6, 2020

tobiasdiez deleted the getting-started branch September 6, 2020 21:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

First draft for en/getting-started.md #297

First draft for en/getting-started.md #297

matthiasgeiger commented Sep 1, 2020 •

edited

Loading

tobiasdiez commented Sep 1, 2020

matthiasgeiger commented Sep 2, 2020

Siedlerchr commented Sep 2, 2020

mlep commented Sep 2, 2020

koppor commented Sep 2, 2020

koppor commented Sep 2, 2020

mlep commented Sep 2, 2020

koppor commented Sep 2, 2020

tobiasdiez commented Sep 4, 2020 •

edited

Loading

matthiasgeiger commented Sep 6, 2020

Siedlerchr Sep 6, 2020

Siedlerchr left a comment

Siedlerchr Sep 6, 2020

tobiasdiez Sep 6, 2020

matthiasgeiger Sep 6, 2020 •

edited

Loading

Siedlerchr Sep 6, 2020

Siedlerchr Sep 6, 2020

Siedlerchr Sep 6, 2020

tobiasdiez Sep 6, 2020

Siedlerchr Sep 6, 2020

tobiasdiez left a comment

tobiasdiez Sep 6, 2020

matthiasgeiger Sep 6, 2020

tobiasdiez Sep 6, 2020

tobiasdiez Sep 6, 2020

tobiasdiez commented Sep 6, 2020

	In order to use the automated feature, it is necessary to set-up a file directory first. To do so, please go to "Options" > "Preferences", go to "File" section and select there an existing folder as the "Main file directory":
	In order to use the automated feature, it is necessary to set-up a file directory. The file directory can either be global, local to a user, or specific for a library. See the help on [Override file directories](https://docs.jabref.org/setup/databaseproperties#override-default-file-directories) for details.
	For beginners, a main file directory is the most simple setup. It can be set in "Options" -> "Preferences" -> "File"

	To test the automatic download of full texts you can click on the "Get full-text" icon next to the file field, or choose "Lookup" -> "Search full text documents online" from the menu. As soon as a full-text is found, the file will be stored in the local file directory and linked to the entry:
	To test the automatic download of full texts you can click on the "Get full-text" icon next to the file field, or choose "Lookup" -> "Search full text documents online" from the menu. As soon as a full-text is found, the file will be stored in the previous defined file directory and linked to the entry:

	The search results will be shown in an window where you can select all the search hits to be added to your library.
	The search results will be shown in an window where you can select all the search hits to be added to your library.
	You also have the option to directly download the fulltext document (if avaiable and possible).


		## Creation of a new library

		A "library" is the main file that saves all the information about your collection of references. The storage format of the file is text-based in the Bibtex standard.

First draft for en/getting-started.md #297

First draft for en/getting-started.md #297

Conversation

matthiasgeiger commented Sep 1, 2020 • edited Loading

tobiasdiez commented Sep 1, 2020

matthiasgeiger commented Sep 2, 2020

Siedlerchr commented Sep 2, 2020

mlep commented Sep 2, 2020

BibTeX

doc

output

biblatex

doc

output

koppor commented Sep 2, 2020

koppor commented Sep 2, 2020

mlep commented Sep 2, 2020

koppor commented Sep 2, 2020

tobiasdiez commented Sep 4, 2020 • edited Loading

matthiasgeiger commented Sep 6, 2020

Choose a reason for hiding this comment

Siedlerchr left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

matthiasgeiger Sep 6, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tobiasdiez left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tobiasdiez commented Sep 6, 2020

matthiasgeiger commented Sep 1, 2020 •

edited

Loading

tobiasdiez commented Sep 4, 2020 •

edited

Loading

matthiasgeiger Sep 6, 2020 •

edited

Loading