Descrizione della struttura delle documentazioni

Descrizione generale della struttura

L'insieme delle documentazioni dei prodotti in tecnologia SAFE X3 è memorizzato nel database.

• tabella ADOCUMENT per la struttura dei paragrafi,
• tabella ADOCCLB per i testi,
• tabella ADOCBLB per i file diversi,
• tabella ADOCFNC per i collegamenti.
• tabella ADOCFLD per gli help su campi.

Il modo in cui i dati vengono memorizzati nelle tabelle è definito nell'allegato sottostante.

Generazione della documentazione

• Una prima funzione di generazione permette di creare, per ciascuna entità da documentare, lo scheletro della documentazione, sotto forma di più paragrafi normalizzati.
• Una seconda funzione di generazione parte da questi dati e dal testo inserito per generare una documentazione finale, in formato HTML. Ogni scheda corrisponde ad un paragrafo, poichè le documentazioni sono organizzate sotto forma di un elenco di paragrafi.

Struttura di un paragrafo

• un codice lingua,
• un tipo di documento:
• La documentazione funzionale (la spiegazione del modo in cui una funzione è utilizzabile) è identificata dal tipo AFC.
• Le documentazioni che descrivono la parametrizzazione (parametri, codici attività, movimenti automatici...) sono identificate dal codice dell'oggetto che le gestisce (ADP, ACV, GAU negli esempi precedenti).
• Le documentazioni diverse (allegati, per esempio, come questo) sono identificate dal codice DI. I menù ed i sotto-menù sono definiti dal codice APM.
• un codice che corrisponde a ciò che è documentato e che permetterà di identificare la documentazione: ad esempio, il codice della funzione, il codice del parametro, il codice attività, il codice del movimento automatico...
• Un livello ed un sotto-livello, che descrivono i concatenamenti di paragrafi.
  Il titolo del primo paragrafo di ciascun livello è riportato in una tabella degli argomenti che permette di puntare direttamente a sezioni di documentazione. Quando in un certo sotto livello esiste più di un paragrafo, viene creata una sotto tabella degli argomenti per il livelli corrispondenti.
• Un codice paragrafo che determina il modo in cui il testo HTML sarà generato.
• Un codice videata che definisce se bisogna inserire, nel menù del paragrafo corrispondente, un'icona che permette di espandere l'help su campi relativi alla videata.
• Un codice attività, ereditato dal dizionario al momento della rigenerazione, che permette generalmente la distinzione tra schede standard e specifiche, ma anche di creare delle documentazioni adattate a determinati dossier generando solo i paragrafi e le documentazioni corrispondenti ai codici attività sul dossier.

Si noti che un paragrafo di codice attività FAL (sempre falso) non è mai considerato dall'elaborazione di generazione, anche se viene richiesta una generazione completa. Ciò permette di disattivare dei paragrafi generati che non si desidera ritrovare in una documentazione.

Una volta eseguita la fase di generazione a partire dal dizionario, è possibile completare le schede create nella tabella ADOCUMENT, e aggiungerne altre (generalmente di tipo diverso). La cancellazione di una scheda nella tabella ADOCUMENT significherà la cancellazione del paragrafo nella documentazione finale (ma se questo paragrafo è generato partendo dal dizionario, verrà ricreato partendo dal dizionario).

E' importante notare che i paragrafi sono elencati nell'ordine nel quale devono apparire (il paragrafo TIT è il primo, ad esempio). Salvo casi particolari e paragrafi generici, (MIS, MIN generalmente), è consigliato rispettare l'ordine.

I paragrafi che esistono si collegano a diverse categorie.

I paragrafi generati automaticamente

Certi paragrafi riprendono automaticamente, con una certa impaginazione, degli elementi generati dal dizionario e/o dalla tabella dei collegamenti.
Vengono chiamati paragrafi generati. In questo caso, durante la generazione della tabella ADOCUMENT, il paragrafo è creato se questi elementi del dizionario o della tabella dei collegamenti lo giustificano, con un testo vuoto. Non è necessario compilare il testo, poichè gli elementi del dizionario saranno automaticamente presentati nel paragrafo. 
Se nella scheda viene inserito un testo, sarà automaticamente aggiunto alla fine del paragrafo. In questo caso, la rigenerazione non cancellerà il paragrafo, anche se in seguito all'evoluzione del dizionario, questo paragrafo non è più giustificato.

I paragrafi creati vuoti o paragrafi classici

Alcuni paragrafi sono creati automaticamente dal dizionario durante la generazione, ma senza alcun testo, poichè si tratta di paragrafi liberi solitamente presenti in un certo tipo di documentazione. Il testo inserito nella tabella ADOCUMENT è allora ripreso nella documentazione finale, senza nessuna impaginazione specifica. Alcuni paragrafi non sono creati automaticamente durante la fase di generazione del dizionario, ma possono essere creati in seguito. Vengono chiamati paragrafi liberi nel seguito di questo documento.

Collegamenti ipertestuali

Salvo casi particolari elencati prima, la creazione di un paragrafo genera una anchor con lo stesso nome nel testo. E' anche possibile creare un collegamento ipertestuale al paragrafo in questione (in questo caso il percorso del collegamento è documento.htm#anchorinvece di essere documento.htm ). Così, per andare direttamente alla documentazione del 3° folder della funzione di gestione degli utenti (GESAUS), si utilizzerà un collegamento a GESAUS.htm#ON3.

I codici di paragrafi che possono esistere in più esemplari in una documentazione devono disporre di un collegamento per paragrafo. In questo caso, il collegamento si esprime nel formato PARAG_LEV_SLEV, dove PARAG è il codice del paragrafo, LEV il livello, e SLEV il sotto-livello. Di conseguenza, per un paragrafo di tipo MIS situato al livello 140, sotto-livello 40 della documentazione ADO_FCT, il collegamento sarà ADO_FCT#MIS_140_40.

I diversi tipi di documentazione

Il campo Tipo di documentazione definisce ciò che sarà documentato.

Il riquadro qui sotto descrive i tipi di documentazione possibili:

Precisazioni su alcune documentazioni

Documentazioni di tipo AFC

La documentazione di tipo AFC è la più completa. Permette di descrivere in dettaglio la funzione, i suoi prerequisiti di parametrizzazione (un insieme di sotto paragrafi automatizzati), l'interfaccia utente (folder integrati da help su campo, bottoni, voci di menù), e gli allegati (stampe, lista errori e tabelle gestite).
Una parte dei paragrafi che la compongono è interamente generata dal dizionario, ma la maggior parte dei paragrafi deve essere inserita. Il codice associato a questa documentazione è il codice della funzione (così come è definito nel dizionario delle funzioni). Il nome del file html corrispondente sarà generato nella sottodirectory FCT della directory di documentazione.
Questa può essere richiamata da qualsiasi videata della funzione grazie al tasto funzionale F1.

Relativamente al file di documentazione HTML generato e per le documentazioni di tipo AFC unicamente, tutti i paragrafi considerati come facenti parte dell'implementazione della funzione sono raggruppati in un altro file HTML, allo scopo di separare la parte funzionale dalla parte tecnica. Nel file HTML originale viene creato un link verso il file HTML di implementazione per ogni tipo di paragrafo coinvolto.
I paragrafi inplicati sono:

• Tutti i paragrafi di livello 30 (i Prerequisiti)
• Tutti i paragrafi di livello 100 (le Tabelle implementate)

Documentazioni di tipo DI

Le documentazioni di tipo DI non sono collegate ad un elemento del dizionario. Permettono di creare degli allegati tecnici, delle documentazioni generiche. Ad esempio, nelle documentazioni standard, GESAWA.htm è la documentazione associata agli eventi di Workflow. GES_AWA.htm, documentazione di tipo DI, è l'allegato tecnico associato.
Le documentazioni di tipo DI sono generate nella directory FCT.
Per evitare di entrare in conflitto con le documentazioni funzionali, la prassi consiste nell'inserire per lo meno un carattere '_' nel codice.

Documentazioni di tipo ACV, ADM, ADP, AHI, AOE, ARP, AWA, CDA, CDE, GAU, PS1, ADC

Le documentazioni di tipo ACV, ADM, ADP, AHI, AOE, ARP, AWA, CDA, CDE, GAU, PS1, ADC sono documentazioni di tipo oggetto, che sono accessibili con Alt + F1 da una funzione di parametrizzazione. Esse permettono di descrivere la scheda corrente dal punto di vista della sua logica di parametrizzazione. In generale, in questo tipo di documentazione si inserisce un breve testo (essenzialmente l'utilizzo o la descrizione del codice in questione, ed eventualmente qualche osservazione). 
Alcuni codici di paragrafi sono specificamente dedicati a questo tipo di documentazione. Il codice associato a questa documentazione è il codice della scheda corrispondente. Il file di documentazione è generato nella sottodirectory OBJ. E' composto dal codice dell'oggetto, seguito dalla chiave della scheda.

Esempi
- Il codice attività BPA è generato con il nome ACV_BPA.htm.
- Il modello di import export BPR è generato col nome AOE_BPR.htm. 

 Si noti che la chiave dei parametri è una chiave in due parti che integra il capitolo corrispondente. Ad esempio, l'help sul parametro ADMUSR (capitolo SUP) è quindi generato col nome ADP_SUP_ADMUSR.htm.

Documentazioni di tipo AML, ATB, ATY

Le documentazioni di tipo AML, ATB, ATY sono documentazioni che descrivono la struttura dei dati.
Sono accessibili dal sommario dell'help.
Esiste un solo paragrafo in questo tipo di documentazione (è il paragrafo di titolo, che permette di far precedere la documentazione generata anche da un eventuale commento). Esse sono generate nella directory MCD, e riprendono il codice della tabella (non prefissato), il codice del tipo di dati prefissati da ATY_, ed il numero di menù locali in formato MEN####.htm (#### é il numero del menù su 4 cifre, completato a sinistra da degli zeri).

Le documentazioni di tipo APM

Le documentazioni di tipo APM sono i menù dell'help.
Queste documentazioni sono generate partendo dal dizionario ed esiste un solo paragrafo per questo tipo di documentazione. E' possibile crearne altre, per descrivere dei menù supplementari che strutturano la documentazione (in questo caso, il paragrafo contiene l'elenco delle documentazioni richiamate). In documentazioni generate di questo tipo è anche possibile aggiungere dei collegamenti a documentazioni supplementari.

Le documentazioni di tipo FI

Le documentazioni di tipo FI permettono semplicemente di estrarre delle documentazioni. La norma di denominazione di queste documentazioni determina il luogo in cui i file vengono creati. Il dettaglio si troverà nel paragrafo corrispondente.

I menù di documentazione

Ogni funzione gestisce delle schede che possono essere documentate dalla funzione di gestione di documentazione, alle seguenti condizioni:

• Definire, nella tabella diversa 910, un codice di documentazione corrispondente al codice dell'oggetto di cui si desidera gestire la documentazione sulla scheda.
• Il tipo di documentazione corrisponde al tipo dell'oggetto, la chiave alla chiave principale della scheda che si documenta (se si tratta di una chiave in più parti, queste sono separate dal carattere di sottolineatura "_").
• Generare le documentazioni in formato HTML (di default, sono create nella directory OBJ, directory degli help su oggetto).
• il richiamo dell'help si fa, su una data scheda, tramite Alt + F1.

Esempi
AFC (help funzionale) corrisponde all'help sulle funzioni, oppure l'oggetto AFC gestisce le funzioni. Lo stesso vale per le documentazioni ADP (parametri), ACT (azioni), ACV (codici attività...).

Dal momento in cui il codice di un oggetto è presente nella tabella diversa 910, un menù Documentazione compare automaticamente nella barra dei menù dell'oggetto corrispondente.
Le funzioni accessibili dal menù sono descritte qui di seguito.

Documentazione / Paragrafi

Questa funzione permette di accedere alla gestione della documentazione, sul primo paragrafo della documentazione (se esiste) associato alla scheda corrente.

Documentazione / Legami

Questa funzione permette di accedere alla gestione dei legami. Questa permette di definire dei collegamenti tra la scheda corrente ed altre schede (ad esempio dei collegamenti tra funzioni e parametri). Questi collegamenti, puramente informativi, permettono di alimentare il meccanismo di generazione degli scheletri di documentazione.

Documentazione / Generazione

Questo menù permette di lanciare una generazione di documentazione. La generazione può essere lanciata anche partendo dal bottone [Generazione] nella parte inferiore della finestra.

Possono essere lanciati tre tipi di generazione, separatamente o simultaneamente:

• la generazione dello scheletro di documentazione partendo dal dizionario (tabelle ADOCUMENT, ADOCBLB, ADOCCLB).
• la generazione della documentazione partendo dalle tabelle precedenti.
• la generazione della documentazione su campo.

Gli intervalli proposti di default tengono conto della scheda in corso, ma possono essere modificati in fase di lancio.

Paragrafi preliminari

Questi paragrafi introducono la documentazione funzionale.

Codice TIT (titolo)

Questo capitolo definisce il titolo della documentazione nella sua descrizione.

Quando la documentazione funzionale è generata a partire dal dizionario, questo capitolo viene creato automaticamente al livello (10,10).

Per le documentazioni del dizionario, (tabelle, menù locali, tipi di dati), di cui è il solo paragrafo, il testo inserito è un testo introduttivo che verrà inserito prima dei riquadri che descrivono la struttura tecnica del dizionario.

Per le documentazioni che descrivono un menù (tipo APM), è possibile aggiungere dei collegamenti ad altri help, identificandoli mediante il loro codice. La codifica di una riga è quindi la seguente:

• sia il codice della funzione (help funzionale). Esempio: GESAUS
• sia il codice dell'help preceduto dal suo tipo, il tutto separato dal carattere "/". Esempio: DI/ADO_FCT
• sia una delle due sintassi precedenti seguita dal carattere "#" e da un tag, per posizionarsi direttamente al centro del documento. Esempio: GESAUS#ON3

Per tutti gli altri tipi di documentazione, è possibile inserire nel testo solo una serie di parole separate da delle virgole, che saranno inserite nel file HTML, nel campo keyword (parola-chiave per le ricerche, che non compare nel testo). Così, in questo caso, non esistono effettivamente paragrafi associati nel documento HTML prodotto (né anchor d'altro canto).

Si gestisce questo tipo di paragrafo per tutti i tipi di documentazione. Se questo paragrafo include un codice attività e se si genera la documentazione per un dossier sul quale questo codice attività non è attivato, la documentazione non viene generata.

In particolare, se questo paragrafo include il codice attività FAL:

• la documentazione finale non viene mai generata.
• neanche una rigenerazione della struttura di documentazione genera nulla (si interrompe se esiste il paragrafo TIT con il codice attività FAL).

D'altro canto, se la descrizione del titolo non è indicata nella scheda, viene ricercata nel dizionario in funzione del contesto. Questo permette generalmente di gestire dei casi specifici, come gli help sulle funzioni RPT*, dove il nome del gruppo deve essere quello del dizionario.

Codice PRE (presentazione)

Questo paragrafo definisce la presentazione dell'entità documentata (funzione, codice attività, parametro di dimensionamento, parametro... è interessata ogni documentazione). E' un paragrafo automaticamente creato vuoto al livello (10,20).

E' il primo paragrafo che compare nella documentazione finale.

 Non è necessario inserire un testo per la presentazione dei codici attività che dipendono da un altro codice (viene usato un testo automatico se il testo è vuoto).

Paragrafi di prerequisiti funzionali

Questi paragrafi descrivono i prerequisiti necessari per l'esecuzione della funzione. Possono essere quindi presentati in qualsiasi documentazione funzionale, anche se alcuni possono essere presentati anche in altre documentazioni (le documentazioni sul codice attività, sulle stampe, sugli eventi di Workflow...).

NOTA per le Documentazioni di tipo AFC (e solo AFC): Nel file di documentazione HTML generato, tutti questi paragrafi di "Prerequisiti" vengono da ora in poi scritti in un file HTML allegato di implementazione, allo scopo di separare la parte funzionale dalla parte tecnica. Nel file HTML originale viene creato un link verso il file HTML di implementazione.

Elenco dei paragrafi:

Codice PRQ (prerequisiti)

Questo paragrafo, che definisce dei prerequisiti, è presente nelle documentazioni sulla funzione, sulle stampe, sui modelli di import/export.

Si tratta di un paragrafo introduttivo creato vuoto al livello (30,10). Nella documentazione sulla funzione, viene creato solo se è creato un altro paragrafo di prerequisiti (mentre viene sempre creato nelle documentazioni su import/export e sulle stampe).

Il testo non è obbligatorio (se non c'è testo, il paragrafo esisterà semplicemente come un intertitolo).

Codice ACV (codici attività)

Presente nella documentazione delle funzioni, così come nella documentazione dei parametri e dei codici attività, si tratta di un paragrafo generatoal livello (30,20) con lo stile 4:

• nella documentazione delle funzioni, viene generato a partire dal dizionario, non appena viene individuato almeno un codice attività (si ricercano nella funzione, nella finestra associata alla funzione, nell'oggetto, la consultazione, le tabelle associate). Si può anche associare un codice attività ad una funzione utilizzando la tabella dei collegamenti ADOCFNC. E' dunque un sotto paragrafo del paragrafo PRQ.
• nella documentazione dei parametri, viene generato a partire da una ricerca nel dizionario utilizzando i collegamenti tra parametro e codice attività.
• Nelle documentazioni che descrivono un codice attività. Viene generatotenendo conto dei codici attività che dipendono dal codice attività documentato (questa diependenza si ritrova nel dizionario).

Durante la generazione della documentazione finale, si ricercano nel dizionario i codici attività con lo stesso algoritmo, e si presentano sotto forma di riquadri con dei collegamenti alla documentazione che descrive il codice attività.

Si noti che la ricerca sistematica in tutto il dizionario, può riportare nella lista, a cascata, un grosso numero di codici attività non desiderati nell'elenco. Esiste una funzionalità specifica che permette di effettuare l'ordinamento: la presenza del codice attività FAL (sempre falso) nei legami di documentazione inibisce la ricerca dei codici attività nel dizionario. Restano allora solo i collegamenti ai codici attività (FAL escluso) strettamente menzionati nei collegamenti.

Codice ADP (parametri)

Presente nella documentazione delle funzioni, così come nella documentazione dei parametri e dei modelli di import/export, si tratta di un paragrafo generatoal livello (30,30) con lo stile 4:

• nella documentazione delle funzioni, definisce l'elenco dei parametri associati alla funzione, ed è generato a partire dai collegamenti tra funzione e parametro o parametro e funzione (sono analizzati anche i legami reciproci). E' dunque un sotto paragrafo del paragrafo PRQ.
• nella documentazione dei parametri, è generato a partire da una ricerca nel dizionario (sono inclusi i parametri dello stesso gruppo e dello stesso capitolo), e dalle associazioni tra parametro e parametro nella tabella dei legami.
• nelle documentazioni che descrivono un modello di import/export, descrive i parametri collegati (ricercati tramite esplorazione dei legami tra modelli e parametri o reciprocamente nella tabella dei legami).

Durante la generazione della documentazione finale, i parametri sono ordinati per famiglia, visualizzati in elenchi con dei collegamenti sulla documentazione che descrive il parametro generale.

Codice ANM (contatori)

Presente nella documentazione delle funzioni, si tratta di un paragrafo generatoal livello (30,40) con lo stile 4, che fornisce l'elenci dei contatori utilizzati dalla funzione. E' generato non appena viene trovato almeno un contatore nella tabella dei legami (è possibile associare un contatore ad una funzione). E' un sotto paragrafo del paragrafo PRQ.

Durante la generazione della documentazione finale, i contatori sono presentati nella lista.

Codice GAU (movimenti automatici)

Presente nella documentazione delle funzioni, si tratta di un paragrafo generatoal livello (30,50) con lo stile 5, che fornisce la lista dei movimenti automatici utilizzati dalla funzione. E' generato non appena viene trovato almeno un movimento automatico nella tabella dei legami (è possibile associare un movimento automatico ad una funzione). E' un sotto paragrafo del paragrafo PRQ, che è preceduto da un intertitolo complementare, di stile appena inferiore allo stile del paragrafo (4 di default), denominato Interfaccia contabile, che introduce globalmente i paragrafi GAU e CDE.

Durante la generazione della documentaizone finale, i movimenti automatici sono presentati in riquadro con un collegamento alla documentazione che li descrive.

Codice CDE (sezioni/default)

Presente nella documentazione delle funzioni, si tratta di un paragrafo generatoal livello (30,60) con lo stile 5, che fornisce l'elenco dei codici sezione utilizzati dalla funzione. E' generato non appena viene trovato almeno un codice sezione nella tabella dei collegamenti (è possibile associare un codice sezione ad una funzione). E' un sotto paragrafo del paragrafo PRQ, che è preceduto da un intertitolo complementare, di stile appena inferiore allo stile del paragrafo (4 di default), denominato Interfaccia contabile, che introduce globalmente i paragrafi GAU e CDE.

Durante la generazione della documentaizone finale, i codici sezione sono presentati in riquadro con un collegamento alla documentazione che li descrive.

Codice HAB (abilitazioni)

Nella documentazione funzionale, questo paragrafo opzionale è normalmente un sotto paragrafo del paragrafo PRQ.

E' un paragrafo generatodi default al livello (30,70), con lo stile 4, non appena si verifica una delle seguenti condizioni:

• la funzione dispone di diritti di accesso in funzione del sito.
• delle opzioni di abilitazione per la funzione sono presenti nel dizionario.
• la funzione è di tipo oggetto (perciò, esistono di default delle opzioni creazione/cancellazione modifica).
• se la funzione è di questo tipo, un codice di accesso viene dichiarato a livello dell'oggetto.

Durante la generazione della documentazione finale, viene creato un insieme di testi automatici in funzione del contesto (gestione per codici di accesso, opzioni di abilitazione presenti nel dizionario...).

Codice TRS (transazioni)

Nella documentazione funzionale, questo paragrafo opzionale è di solito un sotto paragrafo del paragrafo PRQ. Viene generato partendo da collegamenti tra funzioni e transazioni (il legame di tipo TRS associa una funzione alla funzione che permette di parametrizzare le transazioni). La generazione si fa al livello (30,80), con lo stile 4.

Durante la generazione della documentazione finale, queste transazioni sono reimpaginate e vengono inseriti dei collegamenti alla documentazione funzionale corrispondente.

Codice ECC (videata consultazione).

Nella documentazione funzionale, questo paragrafo opzionale è di solito un sotto paragrafo del paragrafo PRQ. Viene generato a partire dal dizionario, ricercando la lista dei codici di consultazione trovati nel dossier dove viene generata la documentazione.

Si ricorda che questo paragrafo viene generato nella stessa posizione del paragrafo TRS, logicamente, poichè i due non possono coesistere (l'uno riguarda le consultazioni, l'altro gli oggetti), ed inoltre essi corrispondono entrambi a delle varianti di videata. La generazione si fa al livello (30,80), con lo stile 4.

Durante la generazione della documentazione finale, questi codici videata sono presentati in riquadro.

Codice PRD (altri prerequisiti)

Presente nella documentazione delle funzioni, si tratta di un paragrafo generatoal livello (30,90) con lo stile 4, che fornisce una serie di altri prerequisiti presentati in forma di sotto paragrafi con degli intertitoli di stile 5:

• il primo tra questi, fornisce l'elenco delle tabelle diverse da aggiornare. E' alimentato dai legami tra funzione e tabelle diverse.
• il secondo fornisce l'elenco delle tabelle del database da aggiornare. E' alimentato dai legami tra funzione e tabelle (mediante il codice AT2, il codice ATB alimenta le tabelle aggiornate).
• il terzo fornisce l'elenco dei menù locali che bisogna indicare. E' alimentato dai legami tra funzione e menù locali.
• l'ultimo sotto paragrafo, denominato Prerequisiti diversi, è presente se è stato aggiunto un testo nella documentazione. Se il testo comincia con un titolo (con un tag di tipo Hn, dove n è un numero), l'inter titolo Prerequisiti diversi non viene inserito.

Descrizione dell'interfaccia

Questi paragrafi generatidescrivono l'organizzazione della finestra di inserimento associata alla funzione. Sono automaticamente generati solo se esiste una finestra associata alla funzione. La generazione finale includerà l'help funzionale se il campo Videata presente nella scheda è alimentato.

Questi paragrafi sono i seguenti:

Codice ECR (descrizione videata)

Questo paragrafo costituisce un'introduzione che permette generalmente di definire il numero di folder, di descrivere le particolarità della lista di selezione se ce ne sono.

Quando la documentazione funzionale è generata a partire dal dizionario, questo capitolo è automaticamente creato al livello (40,50), con lo stile 3.

Codice ENT (testata videata)

Questo paragrafo descrive i campi della testata della finestra (se ce ne sono). Il testo presente viene inserito tale e quale nella documentazione finale. Dal momento in cui il codice della videata è indicato nel parametro, la barra del titolo include una piccola icona a forma di freccia discendente, che espande automaticamente l'elenco dei campi della testata (e gli help corrispondenti). Il testo viene usato in principio per fornire il dettaglio dei campi che compongono la chiave dell'oggetto, o i criteri della consultazione.

Quando la documentazione funzionale è generata a partire dal dizionario, questo capitolo è automaticamente creato al livello (40,100), con lo stile 3, non appena la finestra corrispondente alla funzione utilizza effettivamente una videata di testata.

Codici da ON1 a ONF (folder)

Questi paragrafi descrivono ciascuno dei folder della finestra associata alla funzione. La barra del titolo include una piccola icona a forma di freccia discendente, che espande automaticamente l'elenco dei campi del folder (e gli help corrispondenti) se il campo videata è indicato nella scheda, che è il caso in generazione automatica.

Questo testo è utilizzato in principio per fornire delle informazioni sui campi presenti nel folder (senza per forza fornire il dettaglio dell'help su ogni campo, poichè l'help on line per campo è anche disponibile tramite espansione). In assenza di testo inserito, un testo generico invita l'utente ad espandere l'help su campo.

Quando la documentazione funzionale è generata a partire dal dizionario, questo tipo di capitolo è automaticamente creato al livello 40, partendo dalla descrizione della finestra associata alla funzione. I sotto livelli di generazione sono calcolati a partire dalla posizione del folder (campo ROWMSK), al fine di rispettare l'ordine di presentazione dei folder della funzione nel momento in cui si aggiungono dei folder specifici che devono essere insertiti tra due folder esistenti. Il sotto livello è uguale al range moltiplicato per 200. Così, se i range sono numerati da 1 a10, si ottengono i range 2000, 4000, 6000. Il range massimo possibile è 19800, ed il minimo è 200.

Al momento della generazione della documentazione, i paragrafi che descrivono le azioni Bottoni sui riquadri (clic destro)vengono automaticamente creati dopo il paragrafo collegato a ciascun folder, e vengono numerati di 5 in 5 (al fine di lasciare la possibilità di intercalare dei paragrafi diversi).

Codici BOT (clic sui riquadri)

Questi paragrafi descrivono ognuno delle funzioni accessibili con un clic destro su un riquadro. Possono essercene molteplici (con lo stesso codice: l'anchor corrispondente è dunque BOT_LEV_SLEV, dove LEV è il livello e SLEV il sotto-livello). Ciascuno di questi bottoni deve essere inserito, nell'ordine dei paragrafi, esattamente dopo il paragrafo che descrive il folder sul quale è posizionato.

Quando la documentazione funzionale è generata a partire dal dizionario, questi paragrafi sono automaticamente creati al livello 40, con un intervallo di numerazione di 5 in 5 partendo dal numero del folder (2005, 2010, 2015... dopo il folder di range 10, ad esempio). Lo stile usato di default è il numero 6, ed un inter titolo denominato Funzioni accessibili con clic destro sul riquadro, di stile 5, è posto in testata dei paragrafi consecutivi di questo tipo.

Codici BOU (bottoni)

Questi paragrafi descrivono ognuno dei bottoni accessibili in fondo alla videata. Possono essercene molteplici (con lo stesso codice: l'anchor corrispondente è dunque BOU_LEV_SLEV, dove LEV è il livello e SLEV il sotto-livello). Questi bottoni sono generalmente posizionati dopo i paragrafi associati ai folder. Il primo tra questi è un paragrafo introduttivo, il cui titolo utilizza uno stile standard (3 di default). Il titolo dei capitoli consecutivi BOU che seguono, è presentato come un bottone (che significa che il testo deve corrispondere al testo del bottone). Il testo corrispondente viene quindi posto a destra di ogni bottone.

Quando la documentazione funzionale è generata a partire dal dizionario, questi paragrafi sono automaticamente creati al livello 70, con un sotto livello che inizia da 10 (titolo del capitolo dedicato ai bottoni) e che va di 10 in 10 (20 per il primo bottone, 30 per quello successivo, ecc.).

Codici BME (Barra di menù)

Questi paragrafi descrivono ognuno delle funzioni accessibili dalla barra dei menù. Possono essercene molteplici (con lo stesso codice: l'anchor corrispondente è dunque BME_LEV_SLEV, dove LEV è il livello e SLEV il sotto-livello). Questi paragrafi sono posizionati dopo i paragrafi. Il primo tra questi è un paragrafo introduttivo, il cui titolo utilizza uno stile standard (3 di default). Il titolo dei capitoli consecutivi è in stile standard 4.

Quando la documentazione funzionale è generata a partire dal dizionario, questi paragrafi sono automaticamente creati al livello 80, con un sotto livello che inizia da 10 (titolo del capitolo dedicato ai menù) e che va di 10 in 10 (20 per il primo bottone, 30 per quello successivo, ecc.).

Paragrafi allegati

Questi paragrafi conclusivi forniscono delle informazioni allegate (lista degli errori, stampe, job batch...). Sono i seguenti:

Codice RPT (Stampe)

Presente nella documentazione delle funzioni, si tratta di un paragrafo generatoal livello (50,10) con lo stile 4, che elenca le stampe utilizzate dalla funzione. E' generato a partire dal dizionario (ricerca a partire dai codici di stampa definiti nel dizionario delle funzioni per Stampa e Elenco, cercando se vi sono stampe ad essi associate nella tabella dei codici stampe). Si completa questo elenco di stampe con quelle eventualmente trovate ricercando dei legami tra la funzione e delle stampe nella tabella dei legami.

Durante la generazione della documentazione finale, viene generato un riquadro che contiene le stampe che si possono lanciare dalla funzione, con dei collegamenti ipertestuali alle documentazioni corrispondenti.

Codice ABT (job batch)

Presente nella documentazione delle funzioni, si tratta di un paragrafo generatoal livello (60,10) con lo stile 4, che fornisce l'elenco dei job batch utilizzabili per lanciare la funzione in background. E' generato a partire dal dizionario (ricerca nella tabella dei job batch). Si completa questo elenco di job con quelli eventualmente trovati ricercando dei legami tra la funzione e dei job batch nella tabella dei legami.

Durante la generazione della documentazione finale, viene generato un riquadro che contiene l'elenco dei job esistenti.

Codice ERR (Errori)

Questo paragrafo, il cui testo presente è direttamente inserito nel documento, è dedicato all'elenco degli errori che possono apparire al momento dell'utilizzo della funzione. In questa sede, si inseriscono solo gli errori molto specifici della funzione. Infatti, un insieme di errori generici è elencato in un documento dedicato, ed un collegamento a tale documento viene automaticamente inserito in questo paragrafo. Questo paragrafo è inoltre creato vuoto.

Questo tipo di paragrafo può anche essere usato nella documentazione sui modelli di import/export, con le stesse caratteristiche.

Quando la documentazione funzionale viene generata a partire dal dizionario, questo capitolo è automaticamente creato al livello (80,10), con lo stile 3. Se al paragrafo non è associato alcun testo, un testo segnalerà che i soli errori conosciuti sono errori generici (accessibili tramite il collegamento). Altrimenti, il testo fornisce gli errori ed il testo esplicativo corrispondente. Si raccomanda di utilizzare lo stile H5 per il testo dell'errore, e lo stile di paragrafo di default per la spiegazione, cosa che dà il seguente risultato:

 E' possibile utilizare la sintassi 4GL mess() per fornire il testo dell'errore. Ciò permette di ottenere esattamente il testo dell'errore e la stessa traduzione.

Si avrà dunque, ad esempio:

che al momento della generazione darà

Codice ATB (tabelle gestite)

Presente nella documentazione delle funzioni, così come nella documentazione dei parametri di dimensionamento, dei modelli di import/export, delle stampe, delle regole di Workflow e degli eventi che attivano delle statistiche, si tratta di un paragrafo generatoal livello (100.10) con lo stile 3:

• nella documentazione delle funzioni, è generato a partire dal dizionario, non appena vi viene trovata per lo meno una tabella (vengono ricercate nell'oggetto, nella consultazione). Si può anche associare una tabella ad una funzione, tramite la tabella dei legami.
  NOTA per queste Documentazioni di tipo AFC (e solo AFC): Nel file di documentazione HTML generato, questo paragrafo di "Tabelle implementate" viene da ora in poi scritto in un file HTML allegato di implementazione, allo scopo di separare la parte funzionale dalla parte tecnica. Nel file HTML originale viene creato un link verso il file HTML di implementazione.
• nelle altre documentazioni, il principio è lo stesso: se il dizionario permette di ritrovare delle tabelle, o se vengono trovati dei legami, viene generato il paragrafo.
• nel caso della documentazione dei parametri di dimensionamento, le tabelle elencate sono quelle il cui dimensionamento dipende dal parametro.

Quando si genera la documentazione finale, le tabelle vengono presentate in un riquadro, includendo un collegamento al dizionario delle tabelle ed anche all'oggetto, quando esiste, che permette di generare la tabella in questione. Le tabelle globali di ogni dossier, se ne esistono, sono isolate in un paragrafo dedicato.

Paragrafi specifici

Questi paragrafi possono essere inseriti ovunque nella documentazione, per gestire le eccezioni o i paragrafi supplementari non previsti. Permettono anche di suddividere un paragrafo troppo lungo (la lunghezza del testo inserito senza un paragrafo è limitata per costruzione). Dato che il codice utilizzato per questi paragrafi può essere ripetuto, non vi è anchor con lo stesso nome posizionata al di sopra (vengono tuttavia create delle anchor tecniche, numerate con il codice del paragrafo, seguite dal livello e dal sotto livello, separate dal carattere "_"). Questi paragrafi sono i seguenti:

Codice MIS (Diversi)

Si tratta di un paragrafo diverso presente nella tabella degli argomenti collegati al livello al quale esso si trova. Vengono forniti un titolo, uno stile ed un testo da inserire.

Nella misura in cui possono esistere più paragrafi di questo tipo in una documentazione, l'anchor corrispondente a questi paragrafi è MIS_LEV_SLEV, dove LEV è il livello e SLEV il sotto-livello.

Codice MIN (Diversi)

Si tratta di un paragrafo diverso non presente nella tabella degli argomenti collegati al livello al quale esso si trova. Vengono forniti un titolo, uno stile ed un testo da inserire.

Nella misura in cui possono esistere più paragrafi di questo tipo in una documentazione, l'anchor corrispondente a questi paragrafi è MIN_LEV_SLEV, dove LEV è il livello e SLEV il sotto-livello.

Codice LNK (Collegamenti)

Questo tipo di paragrafo permette di inserire delle tabelle di argomenti sotto forma:

• sia della lista dei legami di testata (situata nelle barra del titolo della documentazione). Ciò suppone che il paragrafo di tipo LNK si trovi allo stesso livello del paragrafo TIT della documentazione corrispondente. Il titolo del paragrafo fornisce allora il titolo del documento corrente così come è definito nell'elenco dei legami.
• sia di una lista di collegamenti (come una tabella degli argomenti) nel caso generico. Questo tipo di paragrafo permette di inserire dei collegamenti a documentazioni non direttamente accessibili nella gerarchia in cui si trova il documento.

Nel caso in cui il collegamento definisca un paragrafo separato, il titolo e lo stile vengono ignorati, e nella tabella degli argomenti non compare alcuna voce. Ma se si desidera aggiungere un titolo a questo paragrafo di collegamenti, è sufficiente farlo precedere da un paragrafo di tipo MIS o MIN.

I collegamenti sono definiti nel testo del paragrafo in una delle seguenti forme:

• CODICE_FUNZIONE
• CODICE_FUNZIONE#anchor
• TIPO/CODICE
• TIPO/CODICE#anchor

Il significato degli elementi è il seguente:

• CODICE_FUNZIONE è il codice di una documentazione funzionale (di tipo AFC o DI): il collegamento punterà alla sotto directory FCT, dove si trova questo tipo di documentazione.
• TIPO corrisponde ai diversi tipi di documentazione: Ad esempio ADC, AD, ACV... Il codice che segue è il codice della documentazione.
• anchor corrisponde ad una anchor di paragrafo, se si desidera posizionarsi direttamente su un certo paragrafo. La anchor è ignorata se si tratta di un collegamento di testata.

Durante la generazione, ogni collegamento viene esplorato: la documentazione corrispondente viene ricercata nella tabella ADOCUMENT (se non esiste, il collegamento non viene inserito) ed il titolo della documentazione viene inserito come testo a supporto del collegamento.

Codice INC (Inclusione)

Questo paragrafo permette di includere così com'è un paragrafo già scritto in un altra documentazione.

Qualsiasi paragrafo può essere incluso, ad eccezione del paragrafo di tipo TIT. Se si vuole riprendere un paragrafo di presentazione associato ad un altra documentazione, il paragrafo INC che lo sostituisce deve essere il primo di questo tipo della documentazione, e deve concatenarsi ad un paragrafo di tipo PRE.

Poiché in una tale documentazione sono possibili più paragrafi INC, l'anchor corrispondente a questi paragrafi è INC_LEV_SLEV, dove LEV è il livello e SLEV il sotto-livello.

Il paragrafo da riprendere deve allora essere identificato nel testo del paragrafo di inclusione, in uno dei due formati seguenti:

• TIPO/CODICE
• TIPO/CODICE/LIVELLO/SOTTO-LIVELLO

Il livello ed il sotto-livello non sono obbligatori (il paragrafo di stesso livello e sotto-livello viene ripreso di default nella documentazione collegata).

Ad esempio, se si vuole inserire il paragrafo relativo al primo folder della scheda utente, che è definito al livello 40 ed al sotto livello 200, si inserirà nel paragrafo di inclusione il seguente testo:

AFC/GESAUS/40/200

Si noti che viene ripreso tutto dal paragrafo di origine (titolo, stile, testo, formattazione, help su campo), tranne il livello ed il sotto-livello che restano quelli d'origine (le rotture di tabelle di argomenti restano così rispettate). Il titolo della tabella degl argomenti corrisponde al titolo del paragrafo INC d'origine, l'anchor creata ed utilizzabile per i collegamenti, corrisponde ad un anchor generica INC_range_sotto-range.

Paragrafi riservati alle altre documentazioni

Questi paragrafi sono specifici per dei tipi di documentazioni diverse dalle documentazioni su funzione. Sono i seguenti:

Codice LEV (livello)

Questo paragrafo è proprio delle documentazioni su parametri. Viene generato partendo dal dizionario al livello (30,10).

Durante la generazione finale, viene generato un testo che precisa il livello di definizione del parametro, così come il nome della variabile globale associata, se esiste. Se non viene trovata nessuna variabile globale, viene inserito un testo che precisa che non ne esistono, tranne se il testo della scheda sia stato indicato (si suppone in questo caso che possa essere portato a menzionare una variabile non dichiarata nel dizionario).

Codice REM (osservazioni)

Questo paragrafo è specifico alle documentazioni su parametri, su movimenti automatici, e su codici sezioni di default. Viene creato vuoto a partire dal dizionario al livello (70,10).

Si presuppone che il testo inserito nella scheda permetta di fare delle osservazioni diverse.

Codice PAR (parametro delle azioni)

Questo paragrafo è specifico alle documentazioni su azioni. Viene generatoa partire dal dizionario al livello (30,10), per permettere di fornire l'elenco dei parametri dell'azione.

Quando si genera la documentazione finale, viene creata una frase introduttiva, seguita da un riquadro che presenta i parametri, la loro descrizione, ed il tipo di dati. In assenza di parametri, viene inserita una frase negativa.

Codice UTI (utilizzo dell'azione)

Questo paragrafo è specifico alle documentazioni su azione. Viene creato vuoto a partire dal dizionario al livello (40,10).

E' previsto che il testo inserito nella scheda descriva gli utilizzi dell'azione.

Se questo paragrafo è rimasto vuoto al momento della generazione della documentazione finale, non viene generato.

Codice ACT (azioni associate alle azioni)

Questo paragrafo è specifico alle documentazioni su azioni. Viene generatoal livello (50,10), per permettere di fornire l'elenco delle azioni collegate all'azione documentata. La generazione si effettua partendo dai collegamenti (e dai collegamenti reciproci) trovati tra azione ed azione.

Durante la generazione della documentazione finale, viene creata una frase introduttiva, seguita da un riquadro che presenta le azioni, con un collegamento alla documentazione corrispondente.

Codice REC (valori consigliati)

Questo paragrafo è specifico alle documentazioni su parametri e su parametri di dimensionamento. Viene creato vuoto nel caso dei parametri, e generato nel caso delle variabili di dimensionamento (viene creata una riga di default se il paragrafo è vuoto, che fornisce il valore trovato nel dossier di riferimento). La creazioni si effettua al livello (30,10).

Il testo inserito nella scheda descrive i valori consigliati per il parametro in questione.

Codice AFC (funzioni interessate)

Questo paragrafo è specifico alle documentazioni su codici attività, sui parametri generali e sulle stampe. Viene generatoal livello (40,10) per i codici attività e le stampe, e a livello (50,10) per i parametri generali, per permettere di fornire:

• l'elenco delle funzioni interessate dal codice attività. La generazione si effettua a partire dai collegamenti reciproci ai legami tra funzioni e codici attività, così come dai codici attività trovati al momento di un'esplorazione sommaria del dizionario (sono riprese solo le funzioni che dipendono direttamente dal codice attività). Durante la generazione della documentazione finale, viene creata una frase introduttiva seguita da un elenco di funzioni con un collegamento alla documentazione corrispondente.
• il mezzo per accedere alla stampa (gruppi di stampe, ed elenco delle funzioni in grado di lanciare la stampa). La generazione si effettua dunque mediante analisi del dizionario e mediante lettura, partendo dai collegamenti reciproci dei legami tra funzioni e stampe. Durante la generazione della documentazione finale, viene creata una frase introduttiva, seguita da un testo automatico che specifica se la stampa è o non è direttamente eseguibile, a quale gruppo di stampe essa appartiene, ed infine un elenco di funzioni in grado di lanciare la stampa con un collegamento alla documentazione corrispondente.
• le funzioni particolarmente influenzate dal parametro.

Codice AT2 (tabelle da indicare)

Questo paragrafo è specifico alle documentazioni su modelli di import/export. Viene generatoal livello (30,30), con lo stile 4, per permettere di generare l'elenco delle tabelle che si prevede siano indicate per poter utilizzare il modello corrispondente, ed è un sotto paragrafo del capitolo PRQ. La generazione di effettua partendo dai legami tra modelli di import/export e tabella (di tipo AT2).

Durante la generazione della documentazione finale, le tabelle vengono presentate in un riquadro, precedute da una frase introduttiva, includendo un collegamento al dizionario delle tabelle ed anche all'oggetto, quando esiste, che permette di gestire la tabella in questione. Le tabelle globali di ogni dossier, se ne esistono, sono isolate in un paragrafo dedicato.

Codice CHO (campi obbligatori)

Questo paragrafo è specifico alle documentazioni su modelli di import/export. Viene  creato vuotoal livello (40,10), per permettere di fornire l'elenco dei campi presumibilmente obbligatori affinchè il modello possa funzionare.

Codice CRI (criteri di lancio)

Questo paragrafo è specifico alle documentazioni su stampe, e alle documentazioni su sotto-programmi.

Nel caso delle stampe, è un paragrafo generatodi default al livello (30,30), con lo stile 4, partendo dai dati del dizionario delle stampe, al fine di permettere di generare i seguenti testi automatici:

• una frase introduttiva, seguita dall'elenco dei parametri della stampa (una frase negativa se non ci sono parametri).
• una frase che specifica il comportamento particolare dei parametri inizio / fine se ve ne sono.
• una frase che specifica, se è il caso, che uno dei parametri può essere inserito con più valori, (segmentazione della stampa).
• una frase che specifica, se è il caso, che viene fatto un filtro dei dati in funzione del sito secondo le abilitazioni dell'utente.
• una frase che specifica, se è il caso, che la stampa può essere stampata solo su una stampante di tipo particolare.

Nel caso dei sottoprogrammi, è un paragrafo generatodi default al livello (20,30), con lo stile 4, a partire dai dati del dizionario dei sottoprogrammi, per poter elencare i parametri da passare al sottoprogramma.

Codice DES (descrizione della stampa)

Questo paragrafo è specifico alle documentazioni su stampe. Viene creato vuotoal livello (40,10), per permettere di descrivere il contenuto della stampa.

Codice CTX (contesto)

Questo paragrafo è specifico alle documentazioni su Workflow, su eventi che attivano le statistiche, e su entry points.

Per gli eventi che attivano le statistiche e il Workflow, questo paragrafo è creato vuotoal livello (30,10), per permettere di descrivere il contesto attivatore.

Per gli entry points, possono esserci più paragrafi di questo tipo. Infatti, una documentazione su entry points può integrare più entry points, ed ogni volta, viene creato un paragrafo APE definito partendo dal livello 20, sotto-livello 10, con un incremento di 10 sui livelli. Un paragrafo CTX associato viene creato allo stesso livello del paragrafo APE corrispondente, al sotto-livello 20. L'anchor corrispondente a questi paragrafi è quindi CTX_LEV_SLEV, dove LEV è il livello e SLEV il sotto-livello.

Quando viene generata la documentazione finale, questo paragrafo integra delle frasi automatiche che segnalano:

• che una transazione è o no in corso (collegamento di tipo TRS del dizionario dei programmi, il valore 1 associato significa che non vi è transazione, il valore 2 che ce n'è una).
• che un file traccia è o non è aperto (collegamento di tipo TRA del dizionario dei programmi , il valore 1 associato significa che non vi è file traccia aperto, il valore 2 che ce n'è uno).

Questo paragrafo integra anche, sotto forma di riquadro, un elenco delle tabelle in linea. Questo elenco si ottiene tramite dei collegamenti del dizionario di programmi verso delle tabelle, un legame di tipo ATB significa che la tabella è aperta poiché indicata nel contesto, un legame di tipo AT2segnala semplicemente che la tabella è aperta. Si noti che questi collegamenti possono essere inseriti come CODICE_TABELLA [ABBREVIAZIONE], quando la tabella non è aperta con la propria abbreviazione principale.

Codice APE (entry point)

Questo paragrafo è specifico alle documentazioni su entry points.

Per gli entry points, possono esserci diversi paragrafi di questo tipo. Infatti, una documentazione su entry points può integrare più entry points, ed ogni volta, viene creato un paragrafo APE definito partendo dal livello 20, sotto-livello 10, con un incremento di 10 sui livelli. L'anchor corrispondente a questi paragrafi è quindi APE_LEV_SLEV, dove LEV è il livello e SLEV il sotto-livello. Un paragrafo CTX associato, viene creato allo stesso livello del paragrafo APE corrispondente, al sotto-livello 20.

Quando la documentazione funzionale è generata a partire dal dizionario, il primo di questi paragrafi è automaticamente creato al livello 20, sotto livello 10. I successivi sono creati dividendo i livelli di 10 in 10. Il codice degli entry points è riconosciuto tramite un collegamento di tipo APE, la descrizione associata fornisce il codice dell'entry point. Si fanno eventualmente seguire a questo collegemento dei collegamenti di tipo ATB, AT2, TRA, TRS, sapendo che l'ordine di dichiarazione è importante (dato che si possono avere più collegamenti APE, si presume che gli altri collegamenti facciano riferimento all'ultimo collegamento dichiarato).

Questo codice di entry point si ritrova in seguito nella descrizione del paragrafo. E' tassativo che questo codice resti in testata del titolo (può essere completato da un testo esplicativo, separato dal codice con uno spazio o una parentesi aperta). Se non viene presa tale precauzione, non si è più in grado di generare correttamente la documentazione finale..

Durante la generazione della documentazione finale, questi paragrafi integrano delle frasi automatiche che segnalano:

• che una transazione è o no in corso (collegamento di tipo TRS del dizionario dei programmi, il valore 1 associato significa che non vi è transazione, il valore 2 che ce n'è una).
• che un file traccia è o non è aperto (collegamento di tipo TRA del dizionario dei programmi , il valore 1 associato significa che non vi è file traccia aperto, il valore 2 che ce n'è uno).

Questi paragrafi integrano anche, sotto forma di riquadro, un elenco delle tabelle in linea. Questo elenco si ottiene tramite dei collegamenti del dizionario di programmi verso delle tabelle, un legame di tipo ATB significa che la tabella è aperta poiché indicata nel contesto, un legame di tipo AT2segnala semplicemente che la tabella è aperta. Si noti che questi collegamenti possono essere inseriti come CODICE_TABELLA [ABBREVIAZIONE], quando la tabella non è aperta con la propria abbreviazione principale.

Codice OPM (modalità operativa)

Questo paragrafo è specifico alle documentazioni su movimenti automatici e su sezioni di default. Viene creato vuotoal livello (30,10), per permettere di descrivere la modalità operativa.

Codice FLW (Descrizione del flusso)

Questo paragrafo è specifico alle documentazioni su workflow. Non è mai creato automaticamente, ma si consiglia di posizionarlo in (40,10). La sua utilità è quella di descrivere i concatenamenti di Workflow nel quale questo evento avviene.

Riassunto delle strutture di paragrafo

Per ciascun tipo di documentazione, si ritroverà qui di seguito, i paragrafi generati e la loro struttura di default (resta inteso che possono essere liberamente inseriti dei paragrafi INC, LNK, MIS e MIN).

AFC (documentazione su funzione)

Questa documentazione, creata nella directory fct, può contenere i seguenti paragrafi:

ADP (documentazione su parametri)

Questa documentazione, creata nella directory obj, può contenere i seguenti paragrafi:

ACT (documentazione su azioni)

Questa documentazione, creata nella directory obj, può contenere i seguenti paragrafi:

In merito al paragrafo PRE, si noti:

• che il suo contenuto è direttamente visualizzato nel dizionario delle azioni, e che è modificabile direttamente da questo dizionario.
• che un testo di default (che specifica che si tratta di un'azione interna non utilizzabile per sviluppi specifici) viene generato nel paragrafo se questo è vuoto.

ACV (documentazione sui codici attività)

Questa documentazione, creata nella directory obj, può contenere i seguenti paragrafi:

ADM (documentazione su variabili di dimensionamento)

Questa documentazione, creata nella directory obj, può contenere i seguenti paragrafi:

AOE (documentazione su modelli di import/export)

Questa documentazione, creata nella directory obj, può contenere i seguenti paragrafi:

ARP (documentazione su stampe)

Questa documentazione, creata nella directory obj, può contenere i seguenti paragrafi:

AWA (documentazione su Workflow)

Questa documentazione, creata nella directory obj, può contenere i seguenti paragrafi:

CDE (documentazione sui codici sezione)

Questa documentazione, creata nella directory obj, può contenere i seguenti paragrafi:

CDA (documentazione su destinazioni)

Questa documentazione, creata nella directory obj, può contenere i seguenti paragrafi:

GAU (documentazione su movimenti automatici)

Questa documentazione, creata nella directory obj, può contenere i seguenti paragrafi:

PS1 (documentazione su attivatori statistici)

Questa documentazione, creata nella directory obj, può contenere i seguenti paragrafi:

ATB (dizionario delle tabelle)

C'è solo un paragrafo in questo tipo di documentazione, che viene creato nella directory mcd:

AML (dizionario dei menù locali)

C'è solo un paragrafo in questo tipo di documentazione, che viene creato nella directory mcd:

ATY (dizionario dei tipi di dati)

C'è solo un paragrafo in questo tipo di documentazione, che viene creato nella directory mcd:

ADC (dizionario degli entry points)

Questa documentazione, creata nella directory obj, può contenere i seguenti paragrafi:

ASU (documentazione su sottoprogrammi)

Questa documentazione, creata nella directory obj, può contenere i seguenti paragrafi:

In merito al paragrafo PRE, si noti:

• che il suo contenuto è direttamente visualizzato nel dizionario dei sottoprogrammi, e che è modificabile direttamente da questo dizionario.
• che un testo di default (che specifica che si tratta di un sotto-programma interno non utilizzabile per sviluppi specifici) viene generato nel paragrafo se questo è vuoto.

AGB (documentazione su variabili)

Questa documentazione, creata nella directory obj, può contenere i seguenti paragrafi:

In merito al paragrafo PRE, si noti:

• che il suo contenuto è direttamente visualizzato nel dizionario delle variabili, e che è modificabile direttamente da questo dizionario.
• che un testo di default (che specifica che si tratta di una variabile interna non utilizzabile per sviluppi specifici) viene generato nel paragrafo se questo è vuoto.

APM (menù intermedi)

Questa documentazione, creata nella directory obj, può contenere i seguenti paragrafi:

AD (Help on line del linguaggio)

Questo tipo di documentazione è utilizzata in due casi:

• quando esiste una funzione di tipo Menù, la generazione crea una documentazione di tipo APM, con un solo paragrafo di tipo TIT. La generazione finale ricerca l'elenco delle funzioni associate al menù per elencare le funzioni corrispondenti. Dei collegamenti possono essere aggiunti direttamente nel paragrafo in questo caso particolare (stessa sintassi del paragrafo LNK), al fine di aggiungere delle righe di menù sotto quelle che sono trovate nel dizionario.
• tutti i menù intermedi associati alle documentazioni diverse (codici attività, eventi Workflow...) sono di tipo APM, con un nome che inizia col codice associato al tipo di documentazione, seguito da un carattere "_", e da un identificativo se necessario (modulo, famiglia) per disporre di menù intermedi, avendo il menù principale il codice TIPO_0. Ad esempio:
• i menù intermedi associati ai codici attività sono: ACV_0 (radice), ACV_1 (codici attività associati al modulo numero 1, ACV_2...
• i menù intermedi associati ai parametri sono: ADP_0 (radice), ADP_TC (parametri della categoria TC), ADP_SUP (parametri della categoria SUP)...

Si noti che la creazione di una documentazione diversa che permetta di realizzare dei menù intermedi deve essere fatta sotto forma di una documentazione di tipo DI, con i seguenti paragrafi: un paragrafo TIT in (10,10), un paragrafo PRE in (10,20), paragrafo che può essere vuoto, eventualmente un primo paragrafo LNK di range (10,30) per permettere di alimentare la barra del titolo con dei collegamenti di navigazione, ed un paragrafo LNK con un range maggiore o uguale a 20, per stabilire l'elenco delle voci di collegamento del menù stesso.

FI (File da estrarre)

Questi tipo di documentazione viene creato nella directory I4G. Questa documentazione ha al momento una struttura libera. Il solo paragrafo obbligatorio è:

Quando quest'unico paragrafo esiste, non viene fatta alcuna generazione di file collegato alla scheda, ma il file collegato, se esiste, è estratto col nome della documentazione. Questa funzionalità è stata fatta per permettere una ripresa tale e quale della documentazione 4GL esistente, ogni documento viene visto come un file nel database.

Se esiste più di un paragrafo (generalmente se si aggiungono dei paragrafi di tipo MIS o MIN), la documentazione viene creata secondo le regole consuete.

Si noti che una documentazione il cui codice termina con carattere _D viene creata con un file che termina col carattere $. Infatti, per evitare di creare delle chiavi che contengano caratteri speciali, si utilizza tale regola di ridenomimazione. Così, le funzioni seg$, chr$, getenv$ sono rappresentate dalle schede SEG_D, CHR_D, GETENV_D.

Altri tipi di documentazione

Questo tipo è particolare: si tratta soltanto di un marker di file da estrarre. Le regole di denominazione sono le seguenti:

• una documentazione di tipo FI e con codice XXXXX_nnn è un marker di file da estrarre nella directory XXXXX (una qualsiasi delle directory standard può così essere definita). Si possono creare tanti paragrafi quanti se ne desidera per definire ad esempio dei gruppi di file diversi.
• una documentazione _nnn è un marker di file da estrarre in tutte le directory XXXXX per le quali esiste una documentazione di tipo FI e con codice XXXXX_nnn. In pratica, quando si genera la documentazione di tipo FI con codice XXXXX_nnn, si verifica se esistono dei paragrafi di uguale livello e sotto livello nella documentazione di tipo FI con codice _nnn corrispondente (il numero deve essere identico). Se ne esistono, questi file vengono estratti per primi. In seguito, si estraggono solo i file collegati alla documentazione con codice XXXXX_nnn. Così, si può definire in questo tipo di documentazione un gruppo comune di file, di cui alcuni possono essere sovrascritti dall'estrazione della documentazione con codice XXXXX_nnn corrispondente.
• la documentazione di tipo FI e con codice _ (un solo carattere "underscore") è un marker di file la cui generazione implica la creazione di file esattamente nella directory radice dell'help. Quando questa documentazione viene generata, si estraggono innanzitutto nella directory radice tutti i file allegati alle documentazioni di tipo FI e con codice _nnn se la prima cifra è 0 (e se il livello ed il sotto livello corrispondono).

Altri tipi di documentazione

Gli altri tipi di documentazione (DI, IN, CS, DL, AM) sono delle documentazioni la cui struttura non è definita (ma le cui directory di generazione sono definite rispetto al tipo). Il solo paragrafo obbligatorio è il paragrafo TIT.

Quando esiste quest'unico paragrafo, non viene fatta nessuna generazione di file collegati alla scheda, ma il file collegato, se esiste, viene estratto col nome della documentazione.

Se esiste più di un paragrafo (generalmente se si aggiungono dei paragrafi di tipo MIS o MIN), la documentazione viene creata secondo le regole consuete.

Le directory di generazione sono indicate nel riquadro che segue:

I sommari della documentazione

I sommari che compongono la documentazione sono collegati ai tipi di documentazione APM. Di norma, in questo caso esiste solo un paragrafo:

Questo paragrafo può contenere, sotto forma di testo, un elenco di codici di documentazione. In questo caso, questo elenco viene aggiunto come altrettanti collegamenti alle documentazioni in questione (il titolo della documentazione viene ripreso nella documentazione in questione). Ciò permette allo stesso tempo, di creare manualmente dei sommari, o di aggiungere ad un sommario esistente dei collegamenti supplementari.

Infatti, quando si genera la documentazione a partire dal dizionario, si generano automaticamente delle documentazioni di tipo APM, con il solo paragrafo TIT. Le codifiche delle documentazioni create, ed i sommari generati nei documenti creati durante la generazione finale, sono descritte nel riquadro qui di seguito:

Per tutti i tipi di documentazione diversi da quelli elencati sopra, è possibile creare una documentazione il cui codice sarà INDEX. Se esiste questa documentazione, un collegamento sarà effettuato direttamente da ogni documentazione di questo tipo nella barra del titolo. Le documentazioni di tipo IN, DL, ad esempio, utilizzano un indice di questo tipo.

Gestione delle tabelle della documentazione

La struttura della documentazione viene salvata nella tabella ADOCUMENT. Questa tabella memorizza, per ogni paragrafo e sotto-paragrafo, le sue caratteristiche (livello, sotto-livello, titolo, codice attività...).

Il testo del paragrafo viene invece salvato a parte nella tabella ADOCCLB. Questa tabella memorizza solo gli elementi di chiave del paragrafo ed il testo del paragrafo stesso.

L'interesse di tale struttura è il seguente:

• l'insieme dei paragrafi standard della documentazione viene salvato nel dossier radice del supervisore.
• Alla creazione di un dossier, si duplica nel dossier la tabella ADOCUMENT, ma in nessun caso i testi dei documenti stessi.
• Ogni aggiunta di un paragrafo specifico viene effettuata nel dossier figlio ed i testi collegati vengono salvati sullo stesso dossier.
• Ogni modifica di un paragrafo standard provoca la copia del record corrispondente della tabella ADOCCLB dal dossier padre al dossier figlio.

Di conseguenza nel dossier figlio vengono memorizzati solo i testi specifici.

Lo stesso vale per i testi legati all'help su campo: i testi standard sono salvati nella tabella ADOCFLD del dossier padre ed i testi specifici sono salvati nel dossier stesso.

Alla generazione della documentazione, viene letta la struttura salvata nel dossier locale e, per ogni paragrafo, si assume in priorità il testo presente nel dossier locale. Se non esiste, si riprende il testo presente nel dossier padre.