[comment {-*- tcl -*- doctools manpage}]
[manpage_begin doctools::changelog n 1.1]
[keywords changelog]
[keywords doctools]
[keywords emacs]
[copyright {2003-2013 Andreas Kupries <andreas_kupries@users.sourceforge.net>}]
[moddesc   {Documentation tools}]
[titledesc {Processing text in Emacs ChangeLog format}]
[category  {Documentation tools}]
[require Tcl 8.2]
[require textutil]
[require doctools::changelog [opt 1.1]]
[description]

This package provides Tcl commands for the processing and reformatting
of text in the [file ChangeLog] format generated by [syscmd emacs].

[section API]

[list_begin definitions]

[call [cmd ::doctools::changelog::scan] [arg text]]

The command takes the [arg text] and parses it under the assumption
that it contains a ChangeLog as generated by [syscmd emacs]. It
returns a data structure describing the contents of this ChangeLog.

[para]

This data structure is a list where each element describes one entry
in the ChangeLog. Each element/entry is then a list of three elements
describing the date of the entry, its author, and the comments made,
in this order. 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 the section.

[para]
[example {
    {
	{
	    date
	    author
	    {
		{
		    {file ...}
		    commenttext
		}
		...
	    }
	}
	{...}
    }
}]

[call [cmd ::doctools::changelog::flatten] [arg entries]]

This command converts a list of entries as generated by
[cmd change::scan] above into a simpler list of plain
text blocks each containing all the information of a
single entry.

[call [cmd ::doctools::changelog::toDoctools] [arg title] [arg module] [arg version] [arg entries]]

This command converts the pre-parsed ChangeLog [arg entries] as
generated by the command [cmd ::doctools::changelog::scan] into a
document in [term doctools] format and returns it as the result of the
command.

[para]

The other three arguments supply the information for the header of
that document which is not available from the changelog itself.

[call [cmd ::doctools::changelog::merge] [arg entries]...]

Each argument of the command is assumed to be a pre-parsed Changelog
as generated by the command [cmd ::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.

[list_end]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]