Prima stesura completa

Text/Markup/Asciidoctor/adoc_include_from_gitea.adoc

@@ -1,25 +1,82 @@
-= rtcwake - Risveglio programmato di un PC Linux
-Risveglio programmato di un PC Linux
-:authors: Celestino Amoroso
-:docinfo: shared
-:encoding: utf-8
-:toc: right
-:toclevels: 4
-:toc-title: Indice Generale
-:icons: font
-:icon-set: fi
-:numbered:
-:table-caption: Tabella
-:figure-caption: Diagramma
-:docinfo1:
-:sectlinks:
-:sectanchors:
-:source-highlighter: rouge
-// :rouge-style: ThankfulEyes
-:rouge-style: gruvbox
-// :rouge-style: colorful
-//:rouge-style: monokay
-
-toc::[]
-
-#todo#
+= asciidoctor - Inclusione file da Gitea
+Inclusione di file referenziati come URL Gitea
+:authors: Celestino Amoroso
+:docinfo: shared
+:encoding: utf-8
+:toc: right
+:toclevels: 4
+:toc-title: Indice Generale
+:icons: font
+:icon-set: fi
+:numbered:
+:table-caption: Tabella
+:figure-caption: Diagramma
+:docinfo1:
+:sectlinks:
+:sectanchors:
+:source-highlighter: rouge
+// :rouge-style: ThankfulEyes
+:rouge-style: gruvbox
+// :rouge-style: colorful
+//:rouge-style: monokay
+
+toc::[]
+
+== 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
+
+
+