Documento complesso

::

Non so se la GuidaGuIT (forum –> Documentazione} abbia il sorgente disponibile per tutti, ma tranne per un punto relativo ai riferimenti incrociati fra volumi diversi, è diviso anche in tre tomi a partire da un unico file sorgente; e da altri tre main file per compilare ciascun tomo; attento: solo il main file, non i file dei capitoli e nemmeno quello delle macro locali o di altri file inclusi.

I riferimenti incrociati da un volume all’altro non ho idea di come si possano fare, se non ricorrendo al pacchetto hyperref e giocando con i target e anchors (vedi documentazione di hyperref: ([tt]texdoc hyperref[/tt]}.

Il concetto è quello di compilare prima l’intero volume con l’indice analitico, poi quando si usano gli altri main file disabilitare la formazione degli indici analitici, ma usare il comando \printindex che stampa il file .ind prodotto nella documentazione completa. Ovviamente per fare questi giochetti bisogna usare il pacchetto imakeidx ([tt]texdoc imakeidx[/tt]).

Il tuo problema è veramente interessante, ma non l’ho mai affrontato se non per quel che riguada cose come quelle che ho descritto sopra.

::

Se il documento è organizzato con la classe book e suddiviso in \part, secondo me una soluzione naturale è trasformare ogni Parte in un volume autonomo.
Il problema è che, dividendo l’opera, si perdono automaticamente:
– i riferimenti incrociati tra volumi;
– la coerenza delle label;
– la possibilità di mantenere un indice analitico comune.

Questo comporta la necessità di mantenere una struttura unica e permettere compilazioni separate.
Supponiamo di avere un’opera composta da tre libri:
Libro I
Libro II
Libro III
Ogni libro deve:
– essere compilabile autonomamente;
– poter citare capitoli, teoremi o sezioni degli altri libri;
– condividere la stessa architettura;
– mantenere un indice analitico coerente.

Una struttura semplice e stabile potrebbe essere questa:
Un preambolo-comune.tex
Un file main-opera.tex
Un file libro-I.tex
Un file libro-II.tex
Un file libro-III.tex
Una cartella chapters contenente:
Sottocartella libro-I con
File cap01.tex
File cap02.tex
…
Sottocartella libro-II con
File cap01.tex
File cap02.tex
…
Sottocartella libro-Iii con
File cap01.tex
File cap02.tex
…

Per rendere fattibile questa struttura userei [code]\xr-hyper[/code] e [code]\externaldocument;[/code] sarà inoltre necessario usare prefissi per evitare collisioni, trattando l’opera come un sistema unico.

In questo modo si ottiene:
– compilazione più veloce;
– riferimenti tra volumi;
– maggiore modularità;
– manutenzione più semplice;
– scalabilità nel tempo.

Il main-opera.tex avrebbe un contenuto simile a questo:
[code]
\documentclass{book}

\input{preambolo-comune}

\begin{document}

\part{Libro I}
\include{chapters/libro-I/cap01}
\include{chapters/libro-I/cap02}

\part{Libro II}
\include{chapters/libro-II/cap01}
\include{chapters/libro-II/cap02}

\part{Libro III}
\include{chapters/libro-III/cap01}

\printindex

\end{document}
[/code]

Ogni libro avrebbe poi un singolo file .tex.

Ad esempio il libro-II.tex il contenuto sarebbe:
[code]
\documentclass{book}

\input{preambolo-comune}

\usepackage{xr-hyper}

\externaldocument[LI-]{libro-I}
\externaldocument[LIII-]{libro-III}

\begin{document}

\part{Libro II}

\include{chapters/libro-II/cap01}
\include{chapters/libro-II/cap02}

\printindex

\end{document}
[/code]

Dove [LI-] e [LII-] sono i prefissi che evitano collisioni.
(chiaramente, nel nostro esempio, negli altri due libri inseriremo \externaldocument riferito ai due libri diversi da quello in cui stiamo operando)

Il pacchetto xr-hyper consente di importare i riferimenti contenuti nei file .aux degli altri documenti.
In pratica, il Libro II può leggere le label del Libro I e del libro III e così via, poiché i riferimenti rimangono attivi tra i diversi volumi.

Esempio pratico:
Nel Libro I:

[code]
\chapter{Principi generali}
\label{chap:principi}
[/code]

Nel Libro II:

[code]
Si veda il capitolo~\ref{LI-chap:principi}.
[/code]
Poiché il Libro I è stato importato con:
[code]
\externaldocument[LI-]{libro-I}
[/code]

La label originale:

[code]chap:principi[/code]

viene automaticamente trasformata in:

[code]LI-chap:principi[/code]

Questo evita collisioni tra label identiche in libri diversi.

Attenzione: quando si separano documenti molto grandi, è frequente avere label con nomi simili.
Ad esempio [code]{chap:introduzione}[/code] potrebbe esistere in più volumi. Senza prefisso, LaTeX non distinguerebbe le label.
Con [code]\externaldocument[LI-]{libro-I}[/code]
si ottiene: [code]\ref{LI-chap:introduzione}[/code] che rende il riferimento univoco.
Quindi è indispensabile usare i prefissi.

Inoltre, per evitare riferimenti troppo tecnici nel testo, è utile definire macro dedicate.

Ad esempio nel preambolo comune si potrebbe inserire:
[code]
\newcommand{\capitololibro}[2]{%
capitolo~\ref{#1} del Libro~#2
}
[/code]
In questo modo potrei scrivere:

[code]Si veda \capitololibro{LI-chap:principi}{I}[/code]

per ottenere in modo abbastanza semplice il seguente output:
Si veda capitolo 3 del Libro I

Lo stesso approccio può essere usato per teoremi, sezioni o
articoli.

La questione più complessa è l’indice.
Qui bisogna segliere:
Ipotesi 1:
Ogni volume contiene soltanto il proprio indice.
Pro: semplice; pulito; compilazione stabile.
Contro:non rappresenta l’opera completa.

Ipotesi 2
L’indice viene prodotto una sola volta nel file main dell’opera e poi incluso nei singoli volumi.
[code]\input{main-opera.ind}[/code]
Pro: tutti i volumi condividono lo stesso indice.
Contro: la numerazione delle pagine si riferirà al main, e non ai singoli volumi che, tipicamente, ricominciano da pag. 1. Praticamente non serve a niente.

Ipotesi 3
Indice strutturale per volume. Questa secondo me è la soluzione la soluzione più elegante.
Esempio:
Responsabilità civile
Libro I, cap. 2
Libro II, cap. 5
Prescrizione
Libro III, cap. 1
Invece di riferirsi a una pagina, l’indice punta a una posizione strutturale.

Una soluzione soddisfacente potrebbe essere quella di fare un indice strutturale per l’intera opera e poi un indice analitico con l’indicazione del numero di pagina per ogni singolo volume.

A mio avviso anche il preambolo comune è un punto delicato della questione:
Non deve contenere soltanto i pacchetti, ma anche tutte le definizioni che devono essere identiche in ogni volume.
L’obiettivo è evitare differenze tra opera completa, Libro I, Libro II, etc.

Un buon preambolo-comune.tex deve contenere:
caricamento dei pacchetti;
definizione di ambienti;
contatori;
stili tipografici;
macro condivise;
gestione dell’indice;
configurazione dei riferimenti.
Ecco un esempio
[code]
% ——————————————————————
% LINGUA E FONT
% ——————————————————————

\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage[italian]{babel}
\usepackage{microtype}

% ——————————————————————
% MATEMATICA
% ——————————————————————

\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{amsthm}

% ——————————————————————
% RIFERIMENTI E LINK
% ——————————————————————

\usepackage{hyperref}
\usepackage{cleveref}

% ——————————————————————
% INDICE ANALITICO
% ——————————————————————

\usepackage{imakeidx}
\makeindex

% ——————————————————————
% GRAFICA
% ——————————————————————

\usepackage{graphicx}
\usepackage{xcolor}

% ——————————————————————
% TABELLE
% ——————————————————————

\usepackage{booktabs}
\usepackage{longtable}

% ——————————————————————
% NUMERAZIONE
% ——————————————————————

\numberwithin{equation}{chapter}

% ——————————————————————
% TEOREMI
% ——————————————————————

\newtheorem{theorem}{Teorema}[chapter]

% ——————————————————————
% MACRO PERSONALIZZATE
% ——————————————————————

\newcommand{\capitololibro}[2]{%
capitolo~\ref{#1} del Libro~#2
}
…
[/code]

Altro consiglio: uno dei problemi più frequenti nei progetti multi-volume riguarda i path. Se il master generale e i master dei singoli libri stanno nella stessa cartella, i riferimenti saranno stabili.
Quindi è meglio [code]\include{chapters/libro-II/cap01}[/code] mentre è meglio evitare [code]\input{../../capitoli/…}[/code] perché rende fragile la struttura.

Conviene inserire il pacchetto xr-hyper nei file dei singoli volumi e non nel preambolo, perchè il main-opera.tex non ha bisogno del comando \externaldocument, mentre i singoli file dei volumi si.

Attenzione anche a centralizzare i contatori se si hanno teoremi, figure, definizioni, ecc., è importante che la numerazione venga definita una sola volta. Ad esempio:
[code]
\newtheorem{theorem}{Teorema}[chapter]
\newtheorem{lemma}[theorem]{Lemma}
\newtheorem{definition}[theorem]{Definizione}
[/code]
Questo evita incoerenze tra volumi.

Spero di averti dato qualche spunto. Sicuramente la questione è complessa; magari c’è qualcuno di più esperto di me che ti darà una soluzione più elegante della mia, ma mi sono divertito a provarci.

::

Non so se possa fare al caso tuo, ma il pacchetto xr permette i riferimenti incrociati tra file (e volumi diversi)

::

Vi ringrazio per le risposte. Ho visto che la GuidaGuit di @OldClaudio non inizia la numerazione della pagine da 1 in ogni volume: ciò non mi darebbe fastidio ed eliminerebbe il problema dei riferimenti complicati, soprattutto se all’inizio di ogni volume riporto l’indice completo dell’opera.

Siccome il mio documento è già strutturato in modo simile a quanto suggerito da @Fede75 proverò la sua proposta di soluzione; grazie anche a @strolego per avermi suggerito il pacchetto xr, che non conoscevo.

Nel frattempo ho dato un’occhiata veloce alla classe memoir: ho visto che oltre a \part ha anche la suddivisione \book. Qualcuno ha esperienze a proposito?

Claudio

::

Il pacchetto xr è stato scritto prima che hyperref esistesse. Se usi hyperref nel tuo documento xr crea un conflitto sottile ma concreto: i riferimenti incrociati esterni vengono risolti correttamente a livello di numero, ma i collegamenti ipertestuali non vengono creati, e in certi casi hyperref emette warning o si comporta in modo imprevedibile sulla gestione degli anchor. Per questo ti suggerivo di usare xr-hyper, che invece è compatibile con hyperref.

::

Grazie per l’importante precisazione!