Dear Bruce,
Thank you — this really helps me to see the issue more clearly from the
user’s point of view.
I had been thinking mainly in terms of completeness and progressive
exposition:
if all the relevant information is present and carefully organised, then
a long
page can still work. But your reference to Diátaxis makes the other side
of the
problem much clearer: documentation must not only contain the right
information;
users must also be able to find the relevant part quickly.
I agree that it is worth separating some of the longer material into more
focused pages, even when the existing content is accurate and useful. The
question is not simply whether a page is too long, but whether it asks
the reader
to navigate several different kinds of documentation at once.
I shall therefore work on making the information easier to find by
dividing it
into separate pages, rather than creating one vast building full of
cupboards,
cellars, winding staircases, drawing rooms, bedrooms, and every other
imaginable
space.
Thank you — this has genuinely clarified the issue for me.
Cheers, JP
Le 19/07/2026 à 00:13, Bruce Horrocks a écrit :
On 18 Jul 2026, at 09:21, Jean-Pierre Delange via ntg-context
<[email protected]> wrote:
Dear all,
I have substantially reorganised and rewritten the ConTeXt Garden wiki on
bibliographies and citations
(https://wiki.contextgarden.net/References_notes_and_floats/Bibliography_and_citations).
As Hans says: impressive.
I would especially appreciate review of the following technical points:
- the descriptions of method=local, method=global, and method=dataset;
- the use of repeat=yes with chapter bibliographies and a final bibliography;
- the examples using several datasets and dataset::key;
- the distinction between citation and list namespaces;
- the examples involving \usecitation and manually written editorial notes;
- the minimal custom specification example.
I've not used bibliographies enough to be able to comment, sorry, but hopefully
someone else will.
I would also appreciate your opinion on the overall structure of the material.
The page has become quite substantial and now serves several purposes at once:
an introduction for beginners, a conceptual reference for intermediate users,
and a guide to advanced project-based workflows.
Would it be preferable to keep this as one comprehensive page, or to divide it
into several linked pages?
It *is* a large page and sub-dividing might help. The last major revision of
the Wiki adopted a structured technical authoring system called Diátaxis.[1]
<https://diataxis.fr/> and there is concise summary here:
<https://danielsieger.com/blog/2023/04/24/framework-for-better-documentation.html>
You can see a skeleton overview page here so there is a template Wiki page
available but I'm not sure how you get it.
<https://wiki.contextgarden.net/Document_structure_and_headlines>
But this is just a recommendation of a technique if you are already thinking of
splitting it up, not a request to do so.
One possible division would be:
1. Bibliography and citations;
2. Multiple bibliographies;
3. Bibliographies in structured editorial projects.
The main page would retain the Quickstart, data formats, the general
bibliography workflow, and citation syntax, while the two longer advanced
sections would become separate pages.
Would you please indicate whether this division would improve readability and
maintenance, or whether the current single-page structure is preferable.
The current version is intentionally detailed, but the structure is progressive
and the table of contents allows readers to stop after the level they need.
Best//JP
[1] Full disclosure: Daniele Procida, the inventor of Diátaxis, is an
acquaintance but we haven't communicated for a few years now.
Regards,
--
Bruce Horrocks
Hampshire, UK
___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the
Wiki!
maillist : [email protected] /
https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive : https://github.com/contextgarden/context
wiki : https://wiki.contextgarden.net
___________________________________________________________________________________
