codedescribe / codelisting

These are expl3 based packages for LaTeX/expl3 code documetation.

codedescribe

provides a series of macros/environments (similar to doc/docx/doc3) for package/classes documentantion

codelisting

provides a few macros for LaTeX code listing/demo.

They are designed to be 'as class independent as possible', no assumption about underlying macros is made. Furthermore, it's assumed that maketitle and the abstract environment were modified by the underlying class, so alternatives (based on the article class) are provided.

For more details, see the documentation, codedescribe.pdf

---

Requirements

• none besides a fairly recent LaTeX distribution as recent as 2022/06/01

(with the new in kernel ProcessKeyOptions and NewDocumentCommand)

Installation

The stable version is available at CTAN.

Usage

Stable version

Just place

  \usepackage{codedescribe}

in the preamble and compile away.

Be aware that options might change between versions, so you have to check them manually.

More Information and documentation

More Information can be found in the documentation; you can find a "bleeding edge" version at the github page

Contacting Author

For bug reports and enhacement suggestions, the preferred way is to use the project's issue page.

For help on how to use the package, suggestions, use the project's discussion page.

• git: https://github.com/alceu-frigeri/codedescribe

---

Copyright 2023-present by Alceu Frigeri

This work may be distributed and/or modified under the conditions of

• The LaTeX Project Public License, version 1.3c (or later), and/or
• The GNU Affero General Public License, version 3 (or later)

This work has the LPPL maintenance status maintained.

The Current Maintainer of this work is Alceu Frigeri

---

This work consists of the files

• codelisting.sty
  • set of macros to typeset and demonstrate LaTeX code

• codedescribe.sty
  • set of macros to document LaTeX packages

• codedescsets.sty
  • sets of locale definitions

• codelstlang.sty
  • sets of listings dialect/language definitions

• codecmm.sty
  • a few auxiliary commands (mostly skip/dim related)

• README.md (this file)
  • quick introduction

• codedescribe.tex
• codedescribe.bib
  • package documentation

• codedescribe.pdf
  • documentation in PDF format

---

Change log

• Version 1.23 (this)
  • codelist partial refaktor: code is more regular, systematic now, regarding listings. some keys got deprecated.
  • shortcuts: making ! active, supporting \tsobj, \tsargs, \tsverb, \tsmeta and \tsmarginnote

• Version 1.22
  • documentation typos.
  • setnewcodekey deprecated in favour of newcodekey.
  • selectlabelset deprecated in favour of setcodelabels
  • fixing readme markdown compatibility issues between github and ctan...
  • new auxiliary command indexgenkey and related keys index gen group and index gen prefix

• Version 1.21
  • fixing #26, long standing hidden bug.
  • add codesyntax* environment (verbatim alternative, #27)
  • adjusted (optimized) the (re)definition of verbatimsc environment #28
  • extended index generating support, keys and \indexcodesetup (related to #25)
  • added a series of index generating auxiliary commands
  • whole index coding depends on global package option index (reducing the overhead when it isn't needed)

• Version 1.20
  • new format keys to adjust spacing in tsobj and margin block placement in codedescribe environment (addressing #23 and #24)
  • new command to copy/duplicate a group format.
  • new setup to help making an index #25
  • new commands for color customization (both codedescribe and codelisting as well)
  • added a listings' key, firstnumber (codelisting, tscode and related)
  • codedescribe package options regarding changes above.
  • documentation review.
• Version 1.19
  • codesyntax new optional parameter, addressing #21
  • new format keys (font and fsize), addressing #22
  • code demo logic reworked, addressing #20
  • new auxiliary package codecmm, to hold those few commands shared between codedescribe and codelisting making them independent from each other.
• Version 1.18
  • new commands and package option for label sets ('locale')
  • addressing #17
  • partially addressing #18 in the documentation
  • new package option to suppress some annoying bad boxes warnings.

• Version 1.17
  • using \pkginfograbProvidesExplPackage
  • New auxiliary package codelstlang.sty (defines a series of listings TeX dialects).
  • New package options to set which TeX dialect(s) to be used.
  • New code key: lststyle to use a listings' user defined style, instead of the provided one.

• Version 1.16b
  • fixing #15 (codesyntax snafu, introduced by last update)

• Version 1.16a
  • code cleanup (better following expl3 convention) and a bit of optimization.

• Version 1.16
  • removing references to expl scratch variables, like \l_tmpa_tl and \l_tmpa_int.
  • using pkginfograb

• Version 1.15
  • pre-compiling regex
  • removing llongblock bool ...
  • #14 (typo... in code)

• Version 1.14
  • footnote work around for hyperref (addressing issue #13)
  • documentation.

• Version 1.13
  • codedescribe/codesyntax/text interaction fine tuning (in longblock case)
  • removing "spurious code" (ancient leftover code).

• Version 1.12
  • Documentation typos and some clarification regarding packages errors/warnings.
  • describe macro defined only inside a describelist environment.
  • Package option added: strict (warnings will be redirected as package errors)

• Version 1.11
  • replacing vspace with skipvertical:n
  • peeking ahead ts commands (for further spacing fine tune).
  • using xpeekahead for the peek ahead part.
  • added a package option: color scheme (see documentation).
  • documentation (specially due to kernel changes regarding key handlers).

• Version 1.10
  • fixing #10 (hopefully for good) by implementing env-peekahead and skip-spacing
  • environments code cleanup.
  • spacing fine tuning
  • deprecating tsremark (should't exist!)
  • implementing #11

• Version 1.9
  • added two keys (letter and other) to Code Keys (see manual)
  • setting, by default, :@ as letters (for expl3) #9
  • added a few option keys to further customize tsobj (bnf style lists, see manual)
  • documentation review (typos, clarity).
  • code cleanup.

• Version 1.8
  • fixes #6, #7 and #8.
  • Added an (optional) index parameter to the code display/demo commands.
  • New command: tsmergedcode, tsexec and setnewcodekey (see documentation).

• Version 1.7
  • fixing #4 (hopefully) for good and
  • working on #5.
  • Added an environment <tsremark> (see documentation).

• Version 1.6
  • fixing issue #3 (long standing (hidden) bug. tsresult now fully respects optional keys.

• Version 1.5b
  • fixing issue #2 (reverting codesyntax bug introduced by v1.5).

• Version 1.5
  • fixing issue #1 (misalignment when missing a codesyntax inner environment).

• Version 1.4
  • The 'new', 'update' and 'info' keys can, now, be used multiple times when declaring a codedescribe environment. (see documentation).

• Version 1.3
  • Added tsresult, a command to just show the result of a stored code (codelisting specific).

• Version 1.2
  • Added format key: basicstyle
• Version 1.1
  • Added two commands to allow <obj-types> customization
  • requiring (now) pifont for EXP/rEXP <format-keys>
  • Added a date command (auxiliary command)

• Version 1.0
  • Initial release by CTAN