Prima stesura completa

Text/Markup/Asciidoctor/adoc_include_from_gitea.adoc

@@ -1,5 +1,5 @@
-= rtcwake - Risveglio programmato di un PC Linux
+= asciidoctor - Inclusione file da Gitea
-Risveglio programmato di un PC Linux
+Inclusione di file referenziati come URL Gitea
 :authors: Celestino Amoroso
 :docinfo: shared
 :encoding: utf-8
@@ -22,4 +22,61 @@ Risveglio programmato di un PC Linux
 
 toc::[]
 
-#todo#
+== Scopo
+Questa guida spiega come includere in un documento Asciidoctor altri documenti che sono referenziati come URL Gitea. Ad esempio, 
+
+  https://git.portale-stac.it/howto/linux/src/branch/main/SSH/README.adoc
+
+
+=== Inclusione file in Asciidoctor
+
+In generale, in un documento Asciidoctor l'inclusione di altri documenti si effettua con la direttiva `include::adoc-file-path-to-include[` _opzioni_ `]`.
+Per ulteriori dettagli vedere https://docs.asciidoctor.org/asciidoc/latest/directives/include/[qui].
+
+L'opzione _leveloffset_ consente di specificare in quale livello della struttura del documento principale dev'essere inserito il documento esterno.
+Ad esempio:
+
+  inlcude::section-01.adoc[leveloffset=+1]
+
+inserisce il documento importando le sue intestazioni con un livello più alto (interno) di quello in cui la direttiva `include::` è compresa (vedere https://docs.asciidoctor.org/asciidoc/latest/directives/include-with-leveloffset/[qui]).
+
+==== Inclusione di documenti referenziati come URL
+Oltre all'inclusione di file provenienti dal filesystem locale, Asciidoctor può incorporare file specificati tramite URL. Esempio.
+
+  include::http://www.mysite.com/docs/section-01.adoc[leveloffset=+1]
+
+==== Abilitazione inclusione URL
+L'inclusione di documenti riferiti come URL è soggetta ad abilitazione esplicita (vedere https://docs.asciidoctor.org/asciidoc/latest/directives/include-uri/[qui]). L'abilitazione si esegue su riga di comando con l'attributo _-a allow-uri-read_.
+Per includere URL quindi il comando `asciidoctor` dev'essere invocato come segue:
+
+  asciidoctor -a allow-uri-read main.adoc
+
+==== Abilitazione inclusione URL in Gitea
+Per attivare l'inclusione delle URL in Gitea arricchire il valore di _RENDER_COMMAND_ aggiungendo l'attributo _allow-uri-read_:
+
+.Sezione markup in gitea.ini
+[source,ini]
+----
+[markup.asciidoc]
+ENABLED = true
+FILE_EXTENSIONS = .adoc,.asciidoc
+RENDER_COMMAND = "asciidoctor -s -a allow-uri-read -a 'newline=\n' -a lang=it -a showtitle --out-file=- -"
+; Input is not a standard input but a file
+IS_INPUT_FILE = false
+----
+
+==== Inclusione di documenti contenuti in Gitea
+Le URL che refenziano documenti Gitea devono puntare ai file originali, non a quelli processati. Ad esempio, l'URL
+
+  https://git.portale-stac.it/howto/linux/src/branch/main/SSH/README.adoc
+
+fa riferimento al file README.adoc contenuto nella directory SSH; il suo contenuto è preprocessato da Asciidoctor prima di essere ritornato al client/browser che lo richiede.
+Tale contenuto è in formato HTML, non nella forma originale adoc.
+
+Per ottenere il contenuto originale (raw) del file bisogna sostiuire nel path la componente *_src_*, posta fra il nome del repository (`howto/linux`) e la componente `branch` con la componente *_raw_*.
+Nell'esempio di sopra, il link raw è:
+
+  https://git.portale-stac.it/howto/linux/raw/branch/main/SSH/README.adoc
+
+
+