Skip to content

Commit

Permalink
s1kd-flatten: Remove "merging" behaviour of -a/-R
Browse files Browse the repository at this point in the history 
Removed the "merging" behaviour of the -R and recently added -a options,
where the contents of the referenced PM would be copied into the main
PM in an S1000D-compliant way. Instead, the tool will always use the
non-S1000D-compliant format of including the whole <pm> element in place
of the <pmRef>.

There are too many different ways that merging can be done, so it's
better to let projects decide how using a separate tool, such as an
XSL transformation on the output of s1kd-flatten. For example, they can
decide to make the output S1000D-compliant by turning the <pm> element
into a <pmEntry>, or copying the contents directly into the main PM.

The -a option has been removed since it no longer has any meaning with
the new behaviour of -R.
  • Loading branch information
@kibook
kibook committed Nov 26, 2024
1 parent 9926666 commit 50f30f5
Show file tree
Hide file tree
Showing 4 changed files with 46 additions and 121 deletions.
12 changes: 1 addition & 11 deletions tools/s1kd-flatten/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,6 @@ reference.

# OPTIONS

- \-a, --recursively-add-entries
Recursively flatten referenced publication modules, copying their
content in to a new PM entry in the "master" publication module. The
PM entry is given the title of the referenced publication module.
The -R (--recursively) option works similarly, but does not create a
new PM entry.

- \-c, --containers
Flatten referenced container data modules by copying the references
inside the container directly in to the publication module. The
Expand Down Expand Up @@ -77,10 +70,7 @@ reference.
Quiet mode. Errors are not printed.

- \-R, --recursively
Recursively flatten referenced publication modules, copying their
content in to the "master" publication module. This is similar to
the -a (--recursively-add-entries) option, but the contents are
copied directly rather than being added to a new PM entry.
Recursively flatten referenced publication modules.

- \-r, --recursive
Search directories recursively.
Expand Down
10 changes: 2 additions & 8 deletions tools/s1kd-flatten/doc/DMC-S1KDTOOLS-A-23-00-00-00A-040A-D_EN-CA.XML
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@
<simplePara>Add -l (--list) option.</simplePara>
</reasonForUpdate>
<reasonForUpdate id="rfu-0002" updateHighlight="1" updateReasonType="urt02">
<simplePara>Add -a (--recursively-add-entries) option.</simplePara>
<simplePara>Change behaviour of -R option.</simplePara>
</reasonForUpdate>
</dmStatus>
</identAndStatusSection>
Expand All @@ -67,12 +67,6 @@
<title>OPTIONS</title>
<para>
<definitionList>
<definitionListItem changeMark="1" changeType="add" reasonForUpdateRefIds="rfu-0002">
<listItemTerm>-a, --recursively-add-entries</listItemTerm>
<listItemDefinition>
<para>Recursively flatten referenced publication modules, copying their content in to a new PM entry in the "master" publication module. The PM entry is given the title of the referenced publication module. The -R (--recursively) option works similarly, but does not create a new PM entry.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-c, --containers</listItemTerm>
<listItemDefinition>
Expand Down Expand Up @@ -154,7 +148,7 @@
<definitionListItem>
<listItemTerm>-R, --recursively</listItemTerm>
<listItemDefinition>
<para changeMark="1" changeType="modify" reasonForUpdateRefIds="rfu-0002">Recursively flatten referenced publication modules, copying their content in to the "master" publication module. This is similar to the -a (--recursively-add-entries) option, but the contents are copied directly rather than being added to a new PM entry.</para>
<para changeMark="1" changeType="modify" reasonForUpdateRefIds="rfu-0002">Recursively flatten referenced publication modules.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
Expand Down
15 changes: 1 addition & 14 deletions tools/s1kd-flatten/doc/s1kd-flatten.1
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,15 +23,6 @@ the data module code, language and/or issue info provided in each
reference.
.SH OPTIONS
.TP
.B \-a, \-\-recursively\-add\-entries
Recursively flatten referenced publication modules, copying their
content in to a new PM entry in the "master" publication module.
The PM entry is given the title of the referenced publication module.
The \-R (\-\-recursively) option works similarly, but does not create a
new PM entry.
.RS
.RE
.TP
.B \-c, \-\-containers
Flatten referenced container data modules by copying the references
inside the container directly in to the publication module.
Expand Down Expand Up @@ -110,11 +101,7 @@ Errors are not printed.
.RE
.TP
.B \-R, \-\-recursively
Recursively flatten referenced publication modules, copying their
content in to the "master" publication module.
This is similar to the \-a (\-\-recursively\-add\-entries) option, but
the contents are copied directly rather than being added to a new PM
entry.
Recursively flatten referenced publication modules.
.RS
.RE
.TP
Expand Down
130 changes: 42 additions & 88 deletions tools/s1kd-flatten/s1kd-flatten.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
#include "xsl.h"

#define PROG_NAME "s1kd-flatten"
#define VERSION "3.5.0"
#define VERSION "4.0.0"

#define ERR_PREFIX PROG_NAME ": ERROR: "
#define WRN_PREFIX PROG_NAME ": WARNING: "
Expand Down Expand Up @@ -53,37 +53,35 @@ static int flatten_container = 0;
static int recursive = 0;
static int recursive_search = 0;
static int remove_unresolved = 0;
static int add_pmentry = 0;

static int only_pm_refs = 0;

static enum verbosity { QUIET, NORMAL, VERBOSE, DEBUG } verbosity = NORMAL;

static void show_help(void)
{
puts("Usage: " PROG_NAME " [-d <dir>] [-I <path>] [-acDfilmNPpqRruvxh?] <pubmodule> [<dmodule>...]");
puts("Usage: " PROG_NAME " [-d <dir>] [-I <path>] [-cDfilmNPpqRruvxh?] <pubmodule> [<dmodule>...]");
puts("");
puts("Options:");
puts(" -a, --recursively-add-entries Recursively flatten referenced PMs, adding a new PM entry for each.");
puts(" -c, --containers Flatten referenced container data modules.");
puts(" -D, --remove Remove unresolved references.");
puts(" -d, --dir <dir> Directory to start search in.");
puts(" -f, --overwrite Overwrite publication module.");
puts(" -h, -?, --help Show help/usage message.");
puts(" -I, --include <path> Search <path> for referenced objects.");
puts(" -i, --ignore-issue Always match the latest issue of an object found.");
puts(" -l, --list Treat input as a list of objects.");
puts(" -m, --modify Modiy references without flattening them.");
puts(" -N, --omit-issue Assume issue/inwork numbers are omitted.");
puts(" -P, --only-pm-refs Only flatten PM refs.");
puts(" -p, --simple Output a simple, flat XML file.");
puts(" -q, --quiet Quiet mode.");
puts(" -R, --recursively Recursively flatten referenced PMs.");
puts(" -r, --recursive Search directories recursively.");
puts(" -u, --unique Remove duplicate references.");
puts(" -v, --verbose Verbose output.");
puts(" -x, --use-xinclude Use XInclude references.");
puts(" --version Show version information.");
puts(" -c, --containers Flatten referenced container data modules.");
puts(" -D, --remove Remove unresolved references.");
puts(" -d, --dir <dir> Directory to start search in.");
puts(" -f, --overwrite Overwrite publication module.");
puts(" -h, -?, --help Show help/usage message.");
puts(" -I, --include <path> Search <path> for referenced objects.");
puts(" -i, --ignore-issue Always match the latest issue of an object found.");
puts(" -l, --list Treat input as a list of objects.");
puts(" -m, --modify Modiy references without flattening them.");
puts(" -N, --omit-issue Assume issue/inwork numbers are omitted.");
puts(" -P, --only-pm-refs Only flatten PM refs.");
puts(" -p, --simple Output a simple, flat XML file.");
puts(" -q, --quiet Quiet mode.");
puts(" -R, --recursively Recursively flatten referenced PMs.");
puts(" -r, --recursive Search directories recursively.");
puts(" -u, --unique Remove duplicate references.");
puts(" -v, --verbose Verbose output.");
puts(" -x, --use-xinclude Use XInclude references.");
puts(" --version Show version information.");
LIBXML2_PARSE_LONGOPT_HELP
}

Expand Down Expand Up @@ -152,10 +150,6 @@ static void flatten_pm_ref(xmlNodePtr pm_ref, xmlNsPtr xiNs)
char pm_fname_temp[PATH_MAX];
char fs_pm_fname[PATH_MAX] = "";

xmlNodePtr xi;
xmlDocPtr doc;
xmlNodePtr pm;

bool found = false;
xmlNodePtr cur;

Expand Down Expand Up @@ -238,65 +232,14 @@ static void flatten_pm_ref(xmlNodePtr pm_ref, xmlNsPtr xiNs)

found = true;

if (recursive) {
xmlDocPtr subpm;
xmlNodePtr pmentry = NULL;
xmlNodePtr content;

if (flatten_ref) {
if (verbosity >= VERBOSE) {
fprintf(stderr, I_INCLUDE, fs_pm_fname);
}

subpm = read_xml_doc(fs_pm_fname);

/* Create a new PM entry to contain the contents of the referenced PM. */
if (add_pmentry) {
xmlChar *title;

pmentry = xmlNewNode(NULL, BAD_CAST "pmEntry");

title = xpath_first_value(subpm, NULL, BAD_CAST "//pmTitle");
xmlNewChild(pmentry, NULL, BAD_CAST "pmEntryTitle", title);
xmlFree(title);

pmentry = xmlAddNextSibling(pm_ref, pmentry);
}

content = first_xpath_node(subpm, NULL, "//content");

if (content) {
xmlNodePtr c;

flatten_pm_entry(content, xiNs);

/* Add the contents to the new PM entry. */
if (add_pmentry) {
for (c = content->children; c; c = c->next) {
if (xmlStrcmp(c->name, BAD_CAST "pmEntry") != 0) {
continue;
}

xmlAddChild(pmentry, xmlCopyNode(c, 1));
}
/* Or, add the contents directly to the main PM. */
} else {
for (c = content->last; c; c = c->prev) {
if (xmlStrcmp(c->name, BAD_CAST "pmEntry") != 0) {
continue;
}
if (xinclude && !recursive) {
xmlNodePtr xi;

xmlAddNextSibling(pm_ref, xmlCopyNode(c, 1));
}
}
}

xmlFreeDoc(subpm);
} else if (flatten_ref) {
if (verbosity >= VERBOSE) {
fprintf(stderr, I_INCLUDE, fs_pm_fname);
}

if (xinclude) {
xi = xmlNewNode(xiNs, BAD_CAST "include");
xmlSetProp(xi, BAD_CAST "href", BAD_CAST fs_pm_fname);

Expand All @@ -306,10 +249,23 @@ static void flatten_pm_ref(xmlNodePtr pm_ref, xmlNsPtr xiNs)
xi = xmlAddPrevSibling(pm_ref, xi);
}
} else {
doc = read_xml_doc(fs_pm_fname);
pm = xmlDocGetRootElement(doc);
xmlAddPrevSibling(pm_ref, xmlCopyNode(pm, 1));
xmlFreeDoc(doc);
xmlDocPtr subpm;

subpm = read_xml_doc(fs_pm_fname);

if (recursive) {
xmlNodePtr content;

content = first_xpath_node(subpm, NULL, "//content");

if (content) {
flatten_pm_entry(content, xiNs);
}
}

xmlAddPrevSibling(pm_ref, xmlCopyNode(xmlDocGetRootElement(subpm), 1));

xmlFreeDoc(subpm);
}
}
} else if (remove_unresolved) {
Expand Down Expand Up @@ -665,10 +621,9 @@ int main(int argc, char **argv)

xmlNodePtr cur;

const char *sopts = "acDd:fxmNPpqRruvI:ilh?";
const char *sopts = "cDd:fxmNPpqRruvI:ilh?";
struct option lopts[] = {
{"version" , no_argument , 0, 0},
{"recursively-add-entries", no_argument , 0, 'a'},
{"help" , no_argument , 0, 'h'},
{"containers" , no_argument , 0, 'c'},
{"remove" , no_argument , 0, 'D'},
Expand Down Expand Up @@ -709,7 +664,6 @@ int main(int argc, char **argv)
}
LIBXML2_PARSE_LONGOPT_HANDLE(lopts, loptind, optarg)
break;
case 'a': recursive = 1; add_pmentry = 1; break;
case 'c': flatten_container = 1; break;
case 'D': remove_unresolved = 1; break;
case 'd': free(search_dir); search_dir = strdup(optarg); break;
Expand Down

0 comments on commit 50f30f5

Please sign in to comment.