doctools::changelog(3tcl)

💖 doctools::changelog — the manual page, but make it cute 💖

okay bestie, so this is the manual for doctools::changelog, living in the Documentation tools corner of the 3tcl manual section, and it's all about processing text in Emacs ChangeLog format. yes. emacs. we're doing this. it's giving vintage but honestly it ate. 🎀

---

✨ SYNOPSIS ✨

package require Tcl 8.5 9

package require textutil

package require doctools::changelog ?1.2?

::doctools::changelog::scan text

::doctools::changelog::flatten entries

::doctools::changelog::toDoctools title module version entries

::doctools::changelog::merge entries...

so yeah, first you gotta have Tcl 8.5 or 9 (both, the way it's written, 8.5 9 — that's literally what it says, no cap), you need textutil in the house, and then the star of the show itself: doctools::changelog, optionally at version 1.2. 💅

---

🌸 DESCRIPTION 🌸

This package hands you a whole lil' toolkit of Tcl commands for processing and reformatting text that's written in the "ChangeLog" format — you know, the kind emacs generates. if you've ever stared at a ChangeLog like 👁️👄👁️, this is your girl.

---

👑 API 👑

💫 ::doctools::changelog::scan text

This one takes the text and parses it, assuming it contains a ChangeLog as generated by emacs. Then it hands back a data structure describing everything inside that ChangeLog. ✨

That data structure? It's a list, and every element in it describes one entry in the ChangeLog. Each element/entry is itself a list of three elements, describing, in this order:

1. the date of the entry
2. its author
3. the comments made

And the last item in each element/entry — the comments — is a list of sections. Each section is described by a list containing two elements: a list of file names, and a string containing the true comment associated with the files of that section. 🫶

{
    {
        date
        author
        {
            {
                {file ...}
                commenttext
            }
            ...
        }
    }
    {...}
}

💫 ::doctools::changelog::flatten entries

This command takes a list of entries like the ones change::scan spits out up there and converts them into a simpler list of plain text blocks — each block carrying all the info of a single entry. less structure, same tea. 🍓

💫 ::doctools::changelog::toDoctools title module version entries

This one takes the pre-parsed ChangeLog entries (the ones from ::doctools::changelog::scan, mwah) and converts them into a document in doctools format, returning that document as the result of the command. 🔥

The other three arguments — title, module, and version — supply the info for the header of that document, because the changelog itself simply does not have it. it's giving "we need outside help for the header, bestie."

💫 ::doctools::changelog::merge entries...

Every argument of this command is assumed to be a pre-parsed Changelog, as generated by ::doctools::changelog::scan. This command merges all of them into a single structure, and collapses multiple entries for the same date and author into a single entry. The new structure is returned as the result of the command. so satisfying. like cleaning your camera roll. 🧚

---

😭 BUGS, IDEAS, FEEDBACK 😭

Real talk: this document, and the package it describes, will undoubtedly contain bugs and other problems. it's not a vibe, it's just true. Please report such things in the category doctools of the Tcllib Trackers at:

http://core.tcl.tk/tcllib/reportlist

Also please report any ideas for enhancements you may have for either the package and/or the documentation. we love ideas. we want them. 💜

When proposing code changes, please provide unified diffs, i.e the output of diff -u.

And note further, bestie: attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. iconic behaviour, tbh. ✨

---

🦋 KEYWORDS 🦋

changelog, doctools, emacs

---

🌈 CATEGORY 🌈

Documentation tools

---

💖 COPYRIGHT 💖

Copyright (c) 2003-2013 Andreas Kupries <andreas_kupries@users.sourceforge.net>

---

and that's the whole page, periodt. 💅 this cutie came from tcllib, version 1.2, and it's dated doctools::changelog(3tcl) — go forth and parse those changelogs, my main character. 🎀✨