Différences
Ci-dessous, les différences entre deux révisions de la page.
| Les deux révisions précédentes Révision précédente Prochaine révision | Révision précédente Prochaine révision Les deux révisions suivantes | ||
|
2_programmation:syntaxe:commentaires:compilation_conditionnelle_et_commentaires [2018/05/25 10:56] joseph.wright |
2_programmation:syntaxe:commentaires:compilation_conditionnelle_et_commentaires [2018/12/04 00:37] jejust |
||
|---|---|---|---|
| Ligne 1: | Ligne 1: | ||
| - | --- | + | ====== Conditional compilation and "comments" ====== |
| - | section: How do I do…? | + | |
| - | subsection: Document management | + | |
| - | permalink: /FAQ-conditional | + | |
| - | date: 2014-06-10 | + | |
| - | --- | + | |
| - | # Conditional compilation and ''comments'' | ||
| While LaTeX (or any other TeX-derived package) isn't really like a | While LaTeX (or any other TeX-derived package) isn't really like a | ||
| compiler, people regularly want to do compiler-like things using it. | compiler, people regularly want to do compiler-like things using it. | ||
| - | Common requirements are conditional ''compilation'' and ''block | + | Common requirements are conditional "compilation" and |
| - | comments'', and several LaTeX-specific means to this end are available. | + | "block comments", and several LaTeX-specific means to this end are available. |
| - | The simple `\newcommand{`\gobble`}`[1]`{}` | + | The simple ''\newcommand{''\gobble''}''[1]''{}'' |
| - | and `\iffalse`` ... ``\fi` aren't really satisfactory (as | + | and ''\iffalse ... \fi'' aren't really satisfactory (as |
| a general solution) for comments, since the matter being skipped is | a general solution) for comments, since the matter being skipped is | ||
| nevertheless scanned by TeX, not always as you would expect. The | nevertheless scanned by TeX, not always as you would expect. The | ||
| scanning imposes restrictions on what you're allowed to skip; this may | scanning imposes restrictions on what you're allowed to skip; this may | ||
| - | not be a problem in _today's_ job, but could return to bite you | + | not be a problem in //today's// job, but could return to bite you |
| tomorrow. For an example of surprises that may come to bite you, | tomorrow. For an example of surprises that may come to bite you, | ||
| consider the following example (derived from real user experience): | consider the following example (derived from real user experience): | ||
| - | ```latex | + | |
| + | <code latex> | ||
| \iffalse % ignoring this bit | \iffalse % ignoring this bit | ||
| consider what happens if we | consider what happens if we | ||
| use \verb+\iftrue+ -- a surprise | use \verb+\iftrue+ -- a surprise | ||
| \fi | \fi | ||
| - | ``` | + | </code> |
| - | The `\iftrue` is spotted by TeX as it scans, ignoring the | + | The ''\iftrue'' is spotted by TeX as it scans, ignoring the |
| - | `\verb` command; so the `\iffalse` isn't terminated by the | + | ''\verb'' command; so the ''\iffalse'' isn't terminated by the |
| - | following `\fi`. Also, `\gobble` is pretty inefficient at | + | following ''\fi''. Also, ''\gobble'' is pretty inefficient at |
| consuming anything non-trivial, since all the matter to be skipped is | consuming anything non-trivial, since all the matter to be skipped is | ||
| copied to the argument stack before being ignored. | copied to the argument stack before being ignored. | ||
| Ligne 35: | Ligne 30: | ||
| If your requirement is for a document from which whole chapters (or | If your requirement is for a document from which whole chapters (or | ||
| the like) are missing, consider the LaTeX | the like) are missing, consider the LaTeX | ||
| - | `\include`/`\includeonly` system. If you `\include` your | + | ''\include''/''\includeonly'' system. If you ''\include'' your |
| - | files (rather than `\input` them — see | + | files (rather than ''\input'' them --- see |
| - | [What's going on in my `\include` commands?](FAQ-include.md)), | + | [[FAQ-include|What's going on in my ''\include'' commands?]]), |
| LaTeX writes macro traces of what's going on at the end of each | LaTeX writes macro traces of what's going on at the end of each | ||
| - | chapter to the `aux` file; by using `\includeonly`, you can give | + | chapter to the ''aux'' file; by using ''\includeonly'', you can give |
| LaTeX an exhaustive list of the files that are needed. Files that | LaTeX an exhaustive list of the files that are needed. Files that | ||
| - | don't get `\include`d are skipped entirely, but the document | + | don't get ''\include''d are skipped entirely, but the document |
| - | processing continues as if they _were_ there, and page, footnote, | + | processing continues as if they //were// there, and page, footnote, |
| and other numbers are not disturbed. Note that you can choose which | and other numbers are not disturbed. Note that you can choose which | ||
| sections you want included interactively, using the | sections you want included interactively, using the | ||
| - | [`askinclude`](https://ctan.org/pkg/askinclude) package. | + | [[ctanpkg>askinclude|askinclude]] package. |
| - | A variant on the `\includeonly` mechanism is offered by the | + | A variant on the ''\includeonly'' mechanism is offered by the |
| - | [`stampinclude`](https://ctan.org/pkg/stampinclude) package, which takes advantage of the pdfTeX | + | [[ctanpkg>stampinclude|stampinclude]] package, which takes advantage of the pdfTeX |
| - | `\pdffilemoddate` command. When an `\include`d file is | + | ''\pdffilemoddate'' command. When an ''\include''d file is |
| - | processed in a LaTeX document, an `aux` file is created | + | processed in a LaTeX document, an ''aux'' file is created |
| holding data such as page-number ranges and chapter/section numbers. | holding data such as page-number ranges and chapter/section numbers. | ||
| - | When `\stampinclude` is included in a document, it compares the | + | When ''\stampinclude'' is included in a document, it compares the |
| file system modification times for each file and its corresponding | file system modification times for each file and its corresponding | ||
| - | `aux` file; the file is only compiled in ''this run'' of the | + | ''aux'' file; the file is only compiled in "this run" of the |
| - | document if the file is newer than its corresponding `aux` | + | document if the file is newer than its corresponding ''aux'' |
| file. The package requires a current pdfTeX, and will also run on | file. The package requires a current pdfTeX, and will also run on | ||
| - | LuaTeX if the [`pdftexcmds`](https://ctan.org/pkg/pdftexcmds) package is available | + | LuaTeX if the [[ctanpkg>pdftexcmds|pdftexcmds]] package is available |
| - | ([`pdftexcmds`](https://ctan.org/pkg/pdftexcmds) emulates the requisite pdfTeX commands using | + | ([[ctanpkg>pdftexcmds|pdftexcmds]] emulates the requisite pdfTeX commands using |
| - | `lua`. Apart from this requirement, [`stampinclude`](https://ctan.org/pkg/stampinclude) is | + | ''lua''. Apart from this requirement, [[ctanpkg>stampinclude|stampinclude]] is |
| a low-maintenace object; include it in your document and it silently | a low-maintenace object; include it in your document and it silently | ||
| does its job. When you want a final version of your document, delete | does its job. When you want a final version of your document, delete | ||
| - | all the `aux` files, and and [`stampinclude`](https://ctan.org/pkg/stampinclude) won't | + | all the ''aux'' files, and and [[ctanpkg>stampinclude|stampinclude]] won't |
| interfere.) | interfere.) | ||
| - | The inverse can be done using the [`excludeonly`](https://ctan.org/pkg/excludeonly) package: this | + | The inverse can be done using the [[ctanpkg>excludeonly|excludeonly]] package: this |
| - | allows you to exclude a (list of) `\include`d files from your | + | allows you to exclude a (list of) ''\include''d files from your |
| - | document, by means of an `\excludeonly` command. | + | document, by means of an ''\excludeonly'' command. |
| If you want to select particular pages of your document, use Heiko | If you want to select particular pages of your document, use Heiko | ||
| - | Oberdiek's [`pagesel`](https://ctan.org/pkg/pagesel) or the [`selectp`](https://ctan.org/pkg/selectp) packages. You | + | Oberdiek's [[ctanpkg>pagesel|pagesel]] or the [[ctanpkg>selectp|selectp]] packages. You |
| can do something similar with an existing PDF document (which | can do something similar with an existing PDF document (which | ||
| - | you may have compiled using `pdflatex` in the first place), | + | you may have compiled using ''pdflatex'' in the first place), |
| - | using the [`pdfpages`](https://ctan.org/pkg/pdfpages) package. The job is then done with a | + | using the [[ctanpkg>pdfpages|pdfpages]] package. The job is then done with a |
| document looking like: | document looking like: | ||
| - | ```latex | + | |
| + | <code latex> | ||
| \documentclass{article} | \documentclass{article} | ||
| \usepackage[final]{pdfpages} | \usepackage[final]{pdfpages} | ||
| Ligne 81: | Ligne 77: | ||
| \includepdf[pages=30-40]{yoursource.pdf} | \includepdf[pages=30-40]{yoursource.pdf} | ||
| \end{document} | \end{document} | ||
| - | ``` | + | </code> |
| (To include all of the document, you write | (To include all of the document, you write | ||
| - | ```latex | + | |
| + | <code latex> | ||
| \includepdf[pages=-]{yoursource.pdf} | \includepdf[pages=-]{yoursource.pdf} | ||
| - | ``` | + | </code> |
| omitting the start and end pages in the optional argument.) | omitting the start and end pages in the optional argument.) | ||
| If you want flexible facilities for including or excluding small | If you want flexible facilities for including or excluding small | ||
| - | portions of a file, consider the [`comment`](https://ctan.org/pkg/comment), [`version`](https://ctan.org/pkg/version) or | + | portions of a file, consider the [[ctanpkg>comment|comment]], [[ctanpkg>version|version]] or |
| - | [`optional`](https://ctan.org/pkg/optional) packages. | + | [[ctanpkg>optional|optional]] packages. |
| - | The [`comment`](https://ctan.org/pkg/comment) package allows you to declare areas of a document to be | + | The [[ctanpkg>comment|comment]] package allows you to declare areas of a document to be |
| included or excluded; you make these declarations in the preamble of | included or excluded; you make these declarations in the preamble of | ||
| - | your file. The command `\includecomment{version-name}` | + | your file. The command ''\includecomment{version-name}'' |
| - | declares an environment `version-name` whose content will | + | declares an environment ''version-name'' whose content will |
| be included in your document, while | be included in your document, while | ||
| - | `\excludecomment{version-name}` defines an environment whose | + | ''\excludecomment{version-name}'' defines an environment whose |
| content will be excluded from the document. The package uses a method | content will be excluded from the document. The package uses a method | ||
| for exclusion that is pretty robust, and can cope with ill-formed | for exclusion that is pretty robust, and can cope with ill-formed | ||
| - | bunches of text (e.g., with unbalanced braces or `\if` commands). | + | bunches of text (e.g., with unbalanced braces or ''\if'' commands). |
| - | (These FAQs employ the [`comment`](https://ctan.org/pkg/comment) package to alter layout | + | (These FAQs employ the [[ctanpkg>comment|comment]] package to alter layout |
| between the printed (two-column) version and the PDF version | between the printed (two-column) version and the PDF version | ||
| - | for browsing; there are `narrowversion` and | + | for browsing; there are ''narrowversion'' and |
| - | `wideversion` for the two versions of the file.) | + | ''wideversion'' for the two versions of the file.) |
| - | [`version`](https://ctan.org/pkg/version) offers similar facilities to `comment.sty` | + | [[ctanpkg>version|version]] offers similar facilities to ''comment.sty'' |
| - | (i.e., `\includeversion` and `\excludeversion` commands); | + | (i.e., ''\includeversion'' and ''\excludeversion'' commands); |
| - | it's far ''lighter weight'', but is less robust (and in particular, | + | it's far "lighter weight", but is less robust (and in particular, |
| cannot deal with very large areas of text being included/excluded). | cannot deal with very large areas of text being included/excluded). | ||
| - | A significant development of [`version`](https://ctan.org/pkg/version), confusingly called | + | A significant development of [[ctanpkg>version|version]], confusingly called |
| - | [`versions`](https://ctan.org/pkg/versions) (i.e., merely a plural of the old package name). | + | [[ctanpkg>versions|versions]] (i.e., merely a plural of the old package name). |
| - | [`Versions`](https://ctan.org/pkg/Versions) adds a command | + | [[ctanpkg>Versions|Versions]] adds a command |
| - | `\markversion{version-name}` which defines an environment | + | ''\markversion{version-name}'' which defines an environment |
| that prints the included text, with a clear printed mark around it. | that prints the included text, with a clear printed mark around it. | ||
| - | [`optional`](https://ctan.org/pkg/optional) defines a command `\opt`; its first argument is | + | [[ctanpkg>optional|optional]] defines a command ''\opt''; its first argument is |
| - | an ''inclusion flag'', and its second is text to be included or | + | an "inclusion flag", and its second is text to be included or |
| excluded. Text to be included or excluded must be well-formed | excluded. Text to be included or excluded must be well-formed | ||
| - | (nothing mismatched), and should not be too big — if a large body of | + | (nothing mismatched), and should not be too big --- if a large body of |
| - | text is needed, `\input` should be used in the argument. | + | text is needed, ''\input'' should be used in the argument. |
| The documentation (in the package file itself) tells you | The documentation (in the package file itself) tells you | ||
| how to declare which sections are to be included: this can be done in | how to declare which sections are to be included: this can be done in | ||
| Ligne 130: | Ligne 127: | ||
| And, not least of this style of conditional compilation, | And, not least of this style of conditional compilation, | ||
| - | [`verbatim`](https://ctan.org/pkg/verbatim) (which should be available in any distribution) | + | [[ctanpkg>verbatim|verbatim]] (which should be available in any distribution) |
| - | defines a `comment` environment, which enables the | + | defines a ''comment'' environment, which enables the |
| dedicated user of the source text editor to suppress bits of a | dedicated user of the source text editor to suppress bits of a | ||
| - | LaTeX source file. The [`memoir`](https://ctan.org/pkg/memoir) class offers the same | + | LaTeX source file. The [[ctanpkg>memoir|memoir]] class offers the same |
| environment. | environment. | ||
| - | An interesting variation is the [`xcomment`](https://ctan.org/pkg/xcomment) package. This | + | An interesting variation is the [[ctanpkg>xcomment|xcomment]] package. This |
| defines an environment whose body is all excluded, apart from | defines an environment whose body is all excluded, apart from | ||
| environments named in its argument. So, for example: | environments named in its argument. So, for example: | ||
| - | ```latex | + | |
| + | <code latex> | ||
| \begin{xcomment}{figure,table} | \begin{xcomment}{figure,table} | ||
| This text is not included | This text is not included | ||
| Ligne 151: | Ligne 149: | ||
| ... | ... | ||
| \end{xcomment} | \end{xcomment} | ||
| - | ``` | + | </code> |
| - | The [`tagging`](https://ctan.org/pkg/tagging) package offers another neat set of syntax, which | + | The [[ctanpkg>tagging|tagging]] package offers another neat set of syntax, which |
| - | allow the user to apply ''tags'' to chunks of text, and to include and | + | allow the user to apply "tags" to chunks of text, and to include and |
| exclude tagged text, according to the tags. For example, the user may | exclude tagged text, according to the tags. For example, the user may | ||
| - | ''use'' text marked with some tags, and to ''drop'' marked with others: | + | "use" text marked with some tags, and to "drop" marked with others: |
| - | ```latex | + | |
| + | <code latex> | ||
| \usetag{<tag list>} | \usetag{<tag list>} | ||
| \droptag{<tag list>} | \droptag{<tag list>} | ||
| - | ``` | + | </code> |
| (the tag lists consist of comma-separated single words). | (the tag lists consist of comma-separated single words). | ||
| There are then commands | There are then commands | ||
| - | ```latex | + | |
| + | <code latex> | ||
| \tagged{<tag list>}{<text>} | \tagged{<tag list>}{<text>} | ||
| - | ``` | + | </code> |
| - | which reproduces the text only if the ‹_tag list_› contains at | + | which reproduces the text only if the <//tag list//> contains at |
| - | least one tag listed in the `\usetag` comand, and | + | least one tag listed in the ''\usetag'' comand, and |
| - | ```latex | + | |
| + | <code latex> | ||
| \untagged{<tag list>}{<text>} | \untagged{<tag list>}{<text>} | ||
| - | ``` | + | </code> |
| - | which only reproduces the text unless the ‹_tag list_› contains | + | which only reproduces the text unless the <//tag list//> contains |
| - | none of the tags mention in the `\droptag` command. | + | none of the tags mention in the ''\droptag'' command. |
| Further commands offer an if-then-else setup, and specify | Further commands offer an if-then-else setup, and specify | ||
| - | `taggedblock` and `untaggedblock` environments | + | ''taggedblock'' and ''untaggedblock'' environments |
| that. | that. | ||
| Another valuable aspect of the problem is covered by the | Another valuable aspect of the problem is covered by the | ||
| - | [`extract`](https://ctan.org/pkg/extract) package. The package allows you to produce a | + | [[ctanpkg>extract|extract]] package. The package allows you to produce a |
| - | ''partial copy'' of an existing document: | + | "partial copy" of an existing document: |
| - | the package was developed to permit production of a ''book of | + | the package was developed to permit production of a |
| - | examples'' from a set of lecture notes. The package documentation | + | "book of examples" from a set of lecture notes. The package documentation |
| shows the following usage: | shows the following usage: | ||
| - | ```latex | + | |
| + | <code latex> | ||
| \usepackage[ | \usepackage[ | ||
| active, | active, | ||
| Ligne 192: | Ligne 194: | ||
| extract-cmd={chapter,section} | extract-cmd={chapter,section} | ||
| ]{extract} | ]{extract} | ||
| - | ``` | + | </code> |
| - | which will cause the package to produce a file `foobar.tex` | + | which will cause the package to produce a file ''foobar.tex'' |
| - | containing all the `figure` and `table` | + | containing all the ''figure'' and ''table'' |
| - | environments, and the `\chapter` and `\section` commands, from | + | environments, and the ''\chapter'' and ''\section'' commands, from |
| - | the document being processed. The new file `foobar.tex` is | + | the document being processed. The new file ''foobar.tex'' is |
| - | generated in the course of an otherwise ordinary run on the ''master'' | + | generated in the course of an otherwise ordinary run on the "master" |
| document. The package provides a good number of other facilities, | document. The package provides a good number of other facilities, | ||
| including (numeric or labelled) ranges of environments to extract, and | including (numeric or labelled) ranges of environments to extract, and | ||
| - | an `extract` environment which you can use to create complete | + | an ''extract'' environment which you can use to create complete |
| ready-to-run LaTeX documents with stuff you've extracted. | ready-to-run LaTeX documents with stuff you've extracted. | ||
| + | |||
| + | ----- | ||
| + | |||
| + | //Source:// [[faquk>FAQ-conditional|Conditional compilation and "comments"]] | ||
| + | |||
| + | {{htmlmetatags>metatag-keywords=(LaTeX,usage) | ||
| + | metatag-og:title=(Conditional compilation and "comments") | ||
| + | metatag-og:site_name=(FAQ LaTeX francophone) | ||
| + | }} | ||
