listings: gli argomenti opzionali di \lstnewenvironment

Carissimi, sto cercando di capire la sintassi del comando di listings \lstnewenvironment, che, stando a quel che dice l’autore del pacchetto, dovrebbe essere analoga a \newenvironment:
`\lstnewenvironment
{}[][]
{}
{}`
Non capisco che cosa sia e a che cosa serva quell'[].

Viene proposto il seguente esempio:
`\lstnewenvironment{pascalx}[1][]
{\lstset{language=pascal,numbers=left,numberstyle=\tiny,float,#1}}
{}`
Come si usa? Nel documento, dove devo scrivere l’argomento corrispondente a #? Mi fate un esempio?

Più importante, perché se lascio vuoto il secondo argomento opzionale, ottengo un errore in compilazione?
`\lstnewenvironment{pascalx}[1]%[] se elimino questo ottengo un errore
{\lstset{language=pascal,numbers=left,numberstyle=\tiny,float,#1}}
{}`

È molto semplice: con la definizione proposta, puoi aggiungere opzioni al tuo ambiente pascalx:
`\begin{pascalx}[morekeywords=…,=,…]
codice
\end{pascalx}`
oppure usarlo com’è:
`\begin{pascalx}
codice
\end{pascalx}`
Già che ci siamo, c’è una cosa che penso sia utile quando si usa listings. Supponi di scrivere un pacchetto che definisce un ambiente per il codice TeX:
`\istnewenvironment{texcode}[1][]
{\lstset{language=TeX,basicstyle=\ttfamily}{}`
L’utente del pacchetto usa volentieri questo ambiente, finché nel corso del lavoro gli capita un brano di codice che richiede \small per poter stare nella pagina. Facile, basterebbe dire
`\begin{texcode}[basicstyle=\ttfamily\small]
codice
\end{texcode}`
C’è un problema, come penso ti accorgerai subito: l’utente è obbligato a sapere quale sia il valore di “basicstyle” definito nel pacchetto. Evidente contraddizione con i principi di LaTeX. 🙂

Soluzione: metti nel pacchetto anche
`\lst@Key{addtobasicstyle}\relax{%
\toks@=\expandafter{\lst@basicstyle #1}%
\edef\lst@basicstyle{\the\toks@}}`
e insegna all’utente di scrivere, se vuole qualche modifica,
`\begin{texcode}[addtobasicstyle=\small]
codice
\end{texcode}`
Ci sono altre parole chiave che possono essere trattate in modo analogo.

Penso che sia un’estensione interessante che si potrebbe proporre al curatore di listings.

Ciao
Enrico

Enrico, ti ringrazio della risposta, davvero interessante! Resta però ancora irrisolto questo dubbio:

Più importante, perché se lascio vuoto il secondo argomento opzionale, ottengo un errore in compilazione?
`\lstnewenvironment{pascalx}[1]%[] se elimino questo ottengo un errore
{\lstset{language=pascal,numbers=left,numberstyle=\tiny,float,#1}}
{}`

😈 E quale errore, se magari volessi menzionarlo? Ma non è necessario che tu lo faccia in un altro messaggio, visto che dovrebbe essere ovvio che con
`\lstnewenvironment{pascalx}[1]
{\lstset{language=pascal,numbers=left,numberstyle=\tiny,float,#1}}
{}`
stai chiedendo che l’ambiente pascalx abbia un argomento OBBLIGATORIO. Se poi scrivi
`\begin{pascalx}
program …
\end{pascalx}`
listings cerca l’argomento sulla stessa riga (è così e non ci si può fare niente) e va nei pasticci.

Ovviamente, con quella definizione,
`\begin{pascalx}{}
program …
\end{pascalx}`
non dà alcun problema.

Ciao
Enrico

Ricapitoliamo. La sintassi del comando \lstnewenvironment è la seguente (copiata pari pari dalla doc. di listings):
`\lstnewenvironment
{}[][]
{}
{}`
Allora, il primo parametro opzionale di \lstnewenvironment, [], rappresenta -se ho ben capito- il numero di argomenti dell’ambiente così definito. In assenza del secondo parametro, [], tale numero indica il numero di argomenti obbligatori dell’ambiente .

Il secondo parametro opzionale, [], rappresenta invece il numero di argomenti che può avere l’ambiente . Se vuoto, l’ambiente può anche essere invocato senza alcun argomento.

In realtà, sono in alto mare, e non ci sto capendo molto. Per tradurre al meglio quell'[] (“argomenti opzionali predefiniti?” Boh…) devo capirci di più. Insomma, rem tene, verba sequentur. E io qui la “rem” non la “tengo” affatto… 😳 😥

La sintassi è identica a quella di \newenvironment. Davvero, lo giuro sul mio onore (citazione da Don Giovanni, musica di W. A. Mozart, libretto di L. Da Ponte, naturalmente).

Il comando \lstnewenvironment ha due argomenti opzionali e due argomenti obbligatori. Il primo argomento opzionale indica il numero di argomenti che avrà l’ambiente che si sta definendo. Se compare il secondo argomento opzionale, l’ambiente che si sta definendo avrà un argomento opzionale, il cui valore di default è proprio il contenuto del secondo argomento opzionale a \lstnewenvironment. Vediamo alcuni esempi; in ognuno do la definizione e i modi di uso.

(1) Ambiente per codice Pascal con didascalia obbligatoria, nessuna possibilità di modificare le opzioni predefinite
`\lstnewenvironment{pascalx}[1]
{\lstset{language=pascal,caption={#1}}{}
\begin{pascalx}{Codice importante}
program …
\end{pascalx}`

(2) Ambiente per codice Pascal con didascalia obbligatoria, e possibilità di modificare le opzioni predefinite
`\lstnewenvironment{pascaly}[2][]
{\lstset{language=pascal,caption={#2},#1}{}
\begin{pascaly}{Codice importante}
program …
\end{pascaly}
\begin{pascaly}[float]{Codice importante}
program …
\end{pascaly}`
A differenza del caso precedente, con l’argomento opzionale puoi aggiungere opzioni da valutare in \lstset; nella definizione (ma solo nella parte “start”) puoi riferirti all’argomento opzionale con #1, agli argomenti obbligatori con #2 e seguenti (se ce n’è più di uno).

Con la prima chiamata l’argomento sostituito al parametro #1 è vuoto, perché questo è il valore di default. Con la seconda chiamata fra le chiavi valutate in \lstset c’è anche “float”.

(3) Ambiente per codice Pascal con didascalia “facoltativa”, senza possibilità di modificare le opzioni predefinite
`\lstnewenvironment{pascalz}[1][Codice Pascal]
{\lstset{language=pascal,caption={#1}}{}
\begin{pascalz}
program …
\end{pascalz}
\begin{pascalz}[Codice Pascal importante]
program …
\end{pascalz}`
Nel primo esempio di uso la didascalia sarà quella “standard”, cioè “Codice Pascal”; nel secondo invece la didascalia sarà “Codice Pascal importante”.

Noto solo ora che nell’Arte manca proprio la parte della descrizione di \newcommand e \newenvironment relativa alla definizione di comandi e ambienti con argomento opzionale. Mi pare una mancanza significativa; c’è perfino sulla “(mica tanto) breve introduzione”.

Ciao
Enrico

Mi accodo qui perché ho un problema che non riesco a risolvere. Ho personalizzato un listato con il comando
`\lstnewenvironment{code}[3][]
{ \lstset{language=chess, caption={ [#1]{\footnotesize{#2}} }, float, label={#3}} }
{}
`
e scrivo il codice con la riga
`\begin{code}{Algoritmo Minimax con espansione cieca.}{Algoritmo Minimax con espansione cieca}{cod:minimax}
bla bla bla…
\end{code}
`

solo che il secondo e il terzo argomento non vengono passati. Qual’è il modo corretto di scriverli?
E inoltre, nel caption passo due argomenti perché vorrei differenziare la didascalia del codice da qella visualizzata nell’elenco dei codici sorgente, è giusto fare come ho scritto io?
Ultima cosa, ho inserito float per far si che i listati non vengano spezzati su due pagine, come faccio a specificare “htb” ecc..?
Grazie mille