emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Jens Neuhalfen <jens@neuhalfen.name>
To: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Cc: Org Mode List <emacs-orgmode@gnu.org>
Subject: Re: [wip-cite-new] Merging tomorrow?
Date: Thu, 8 Jul 2021 09:56:57 +0200	[thread overview]
Message-ID: <BF880B41-03F0-45FA-BE87-0FD7DB3BF226@neuhalfen.name> (raw)
In-Reply-To: <87lf6hr74u.fsf@nicolasgoaziou.fr>

Hi Nicolas,

first: thank you for all the work, especially for thinking of documentation for end users. My biggest struggle with the current org (and emacs) documentation is the lack of end-to-end examples. This makes it incredibly difficult to get things working. It often is like „this is a big puzzle, some pieces are in other boxes and we don’t provide a picture of how the final puzzle will look like“. The documentation often makes sense once I get it running, though . But this is to late.

This being the motivation, I would greatly appreciate the following:

——— snip ———-
Consider the following minimal viable example where an org file with one bibtex file is rendered to pdf and html.

This is the BibTex file
#+begin_example bibtex
….
#+end_example

This is the org file
#+begin_example org
….
#+end_example

and this is the rendered html/Latex 

- picture 1
- screenshot 2

This has been achieved with the following minimal configuration:

#+begin_example elisp 
….
#+end_example

As you can see in line 42 the … etc, etc

If you would like to use two bibtex files you would need to change …

#+begin_example elisp 
….
; change line 14 in the sample for one file like this:
(…)
…
#+end_example

——- snap ——-


That kind of documentation would have made many, many hours of frustrating „search in google/github for a solution someone else has found“ and replace it with „wow that was actually quite beginner friendly!“. Pictures also make it much easier to visualize what is actually achieved.

Cheers
Jens

> On 8. Jul 2021, at 02:18, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
> 
> Hello,
> 
> I think the "wip-cite-new" branch is in good shape now. As
> a consequence, I'd like to merge it tomorrow.
> 
> It is documented, but the documentation is scattered across the various
> "oc" libraries, and some threads in the mailing list. I'll do a summary
> here, from a user point of view.
> 
> --8<---------------cut here---------------start------------->8---
> Basically, in order to use it, you need to first set-up a bibliography,
> using one or more "bibliography" keywords. <C-c '> on such a keyword
> visits the related file. Out of the box, Org supports JSON-CSL and
> BibTeX (or biblatex) bibliographies.
> 
> Then, citations can be inserted with the following syntax:
> 
>  [cite/style:common prefix ;prefix @key suffix; ... ; common suffix]
> 
> Spaces are meaningful except those after the initial colon and before
> the closing bracket.
> 
> Every part of the syntax is optional, except the brackets, "cite" and
> the colon. Also the citation must contain at least a key. So its minimal
> form is:
> 
>  [cite:@key]
> 
> The "style" part is detailed below, in the part related to export.
> 
> Org can insert or edit citations with <C-c C-x @> (and delete them with
> <C-u C-c C-x @>), follow them with <C-c C-o>, fontify them, and export
> them. These four actions (insert, follow, activate, and export) are
> called capabilities.  Libraries responsible for these capabilities are
> called citation processors.
> 
> You can select one citation processor for each capability, independently
> on the others, through the following variables:
> 
> - org-cite-activate-processor
> - org-cite-export-processors
> - org-cite-follow-processor
> - org-cite-insert-processor
> 
> Out of the box, Org provides the "basic" (in "oc-basic.el") processor
> for all of these tasks. It also boasts processors dedicated for export:
> "csl", "natbib" and "biblatex".
> 
> During export, output for citations is controlled by their style, which
> is an Org label that the export processor may recognize and associate to
> a specific display, or fall-back to a default style (called "nil"). For
> example, most processors support "noauthor" and "text" styles. 
> 
> Some styles can accept a variant, with the syntax "style/variant".
> Again, it's up to the processor to associate it to a specific display.
> Common variants include "bare", "caps" or "full".  They also accept
> short-hands, like "b", "c" and "f".  Please refer to the export
> processors' libraries ("oc-basic.el", "oc-csl.el", …) for more information.
> 
> It is possible to define a default style for a whole document (with
> "cite_export"), or for all documents (with `org-cite-export-processors').
> 
> References are displayed with the "print_bibliography" keyword. It is
> possible to add parameters to its value, as some export processors could
> make use of them.
> --8<---------------cut here---------------end--------------->8---
> 
> Please let me know if there are any objections to the merge.
> 
> Regards,
> -- 
> Nicolas Goaziou
> 


  parent reply	other threads:[~2021-07-08  7:57 UTC|newest]

Thread overview: 35+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-07-08  0:17 [wip-cite-new] Merging tomorrow? Nicolas Goaziou
2021-07-08  0:29 ` William Denton
2021-07-08  2:12 ` Thomas S. Dye
2021-07-08  3:18   ` Matt Price
2021-07-08  8:12     ` Greg Minshall
2021-07-08 10:09     ` Timothy
2021-07-08  3:47 ` Timothy
2021-07-08  6:31   ` Bruce D'Arcus
2021-07-08  6:47     ` Joost Kremers
2021-07-08 10:17     ` Timothy
2021-07-08 10:26       ` Nicolas Goaziou
2021-07-08 11:15         ` Bruce D'Arcus
2021-07-08 11:33           ` John Kitchin
2021-07-08 13:31         ` Timothy
2021-07-08 14:27           ` Bruce D'Arcus
2021-07-08 21:31             ` William Denton
2021-07-09  7:58               ` Timothy
2021-07-09  8:06                 ` Eric S Fraga
2021-07-08 14:36           ` Nicolas Goaziou
2021-07-08 11:39   ` Eric S Fraga
2021-07-08  7:56 ` Jens Neuhalfen [this message]
2021-07-08 11:42 ` Eric S Fraga
2021-07-08 11:50   ` Nicolas Goaziou
2021-07-08 12:49     ` Eric S Fraga
2021-07-09 13:36 ` William Denton
2021-07-09 16:07   ` Eric S Fraga
2021-07-13 15:50 ` John Kitchin
2021-08-20 13:37 ` Eric S Fraga
2021-08-20 13:46   ` Eric S Fraga
2021-08-20 13:47     ` Bruce D'Arcus
2021-08-20 13:55       ` Eric S Fraga
     [not found]       ` <87eeaonp4x.fsf@ucl.ac.uk>
2021-08-20 15:06         ` Bruce D'Arcus
2021-08-20 15:20           ` John Kitchin
2021-08-20 15:31             ` Bruce D'Arcus
2021-08-20 15:56       ` Eric S Fraga

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=BF880B41-03F0-45FA-BE87-0FD7DB3BF226@neuhalfen.name \
    --to=jens@neuhalfen.name \
    --cc=emacs-orgmode@gnu.org \
    --cc=mail@nicolasgoaziou.fr \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).