genhtml: Add option to change HTML header text

Introduce new command-line option --header-title and associated lcovrc
option genhtml_header that can be used to change the header text shown
at the top of each generated HTML page.

[oberpar: Split original commit, added commit message, fixed typos and
          capitalization, reworded --title text to make difference more
          visible, some man-page rewording]

Signed-off-by: Henry Cox <[email protected]>

Author: henry2cox

Diff for: bin/genhtml

@@ -257,7 +257,8 @@ our %test_description;	# Hash containing test descriptions if available
 our $date = get_date_string();
 
 our @info_filenames;	# List of .info files to use as data source
-our $test_title;	# Title for output as written to each page header
+our $header_title;	# Title at top of HTML report page (above table)
+our $test_title;	# Title shown in header table of each page
 our $output_directory;	# Name of directory in which to store output
 our $base_filename;	# Optional name of file containing baseline data
 our $desc_filename;	# Name of file containing test descriptions
@@ -354,6 +355,7 @@ if ($config || %opt_rc)
 	# Copy configuration file and --rc values to variables
 	apply_config({
 		"genhtml_css_file"		=> \$css_filename,
+		"genhtml_header"		=> \$header_title,
 		"genhtml_hi_limit"		=> \$hi_limit,
 		"genhtml_med_limit"		=> \$med_limit,
 		"genhtml_line_field_width"	=> \$line_field_width,
@@ -401,6 +403,7 @@ $br_coverage	= $lcov_branch_coverage if (!defined($br_coverage));
 
 # Parse command line options
 if (!GetOptions("output-directory|o=s"	=> \$output_directory,
+		"header-title=s"        => \$header_title,
 		"title|t=s"		=> \$test_title,
 		"description-file|d=s"	=> \$desc_filename,
 		"keep-descriptions|k"	=> \$keep_descriptions,
@@ -451,6 +454,10 @@ if (!GetOptions("output-directory|o=s"	=> \$output_directory,
 	if ($no_sort) {
 		$sort = 0;
 	}
+
+	if (defined($header_title)) {
+		$title = $header_title;
+	}
 }
 
 @info_filenames = @ARGV;
@@ -622,8 +629,9 @@ Operation:
 
 HTML output:
   -f, --frames                      Use HTML frames for source code view
-  -t, --title TITLE                 Display TITLE in header of all pages
+  -t, --title TITLE                 Show TITLE in header table of each page
   -c, --css-file CSSFILE            Use external style sheet file CSSFILE
+      --header-title BANNER         Banner text at top of each HTML page
       --no-source                   Do not create source code view
       --num-spaces NUM              Replace tabs with NUM spaces in source view
       --highlight                   Highlight lines with converted-only data

Diff for: lcovrc

@@ -12,6 +12,10 @@
 # same as 'genhtml --dark-mode ....'
 #genhtml_dark_mode = 1
 
+# Header text to use at top of each page
+# Default is "LCOV - coverage report"
+#genhtml_header = Coverage report for my project
+
 # Specify coverage rate limits (in %) for classifying file entries
 # HI:   hi_limit <= rate <= 100         graph color: green
 # MED: med_limit <= rate <  hi_limit    graph color: orange

Diff for: man/genhtml.1

@@ -17,6 +17,9 @@ genhtml \- Generate HTML view from LCOV coverage data files
 .RB [ \-o | \-\-output\-directory
 .IR output\-directory ]
 .br
+.RB [ \-\-header-title
+.IR banner ]
+.br
 .RB [ \-t | \-\-title
 .IR title ]
 .br
@@ -204,13 +207,30 @@ project size, a lot of files and subdirectories may be created.
 .RS
 Display 
 .I title
-in header of all pages.
+in header table of all pages.
 
 .I title
-is written to the header portion of each generated HTML page to
-identify the context in which a particular output
+is written to the "Test:"-field in the header table at the top of each
+generated HTML page to identify the context in which a particular output
 was created. By default this is the name of the tracefile.
 
+A potential use is to specify a test run name, or a version control system
+identifier that indicates the code level that was tested.
+
+.RE
+.BI "\-\-header\-title " BANNER
+.RS
+Display
+.I BANNER
+in header of all pages.
+
+.I BANNER
+is written to the header portion of each generated HTML page. By default this
+simply identifies this as an LCOV coverage report.
+
+A potential use is to specify the name of the project or project branch and
+build ID.
+
 .RE
 .BI "\-d " description\-file
 .br

Diff for: man/lcovrc.5

@@ -54,6 +54,10 @@ section 'OPTIONS' below.
 #genhtml_dark_mode = 1
 .br
 
+# Alternate header text to use at top of each page
+.br
+#genhtml_header = Coverage report for my project
+
 # Coverage rate limits
 .br
 genhtml_hi_limit = 90
@@ -323,6 +327,19 @@ This option corresponds to the \-\-css\-file command line option of
 By default, a standard CSS file is generated.
 .PP
 
+.BR genhtml_header " ="
+.I string
+.IP
+Specify header text to use at top of each HTML page.
+.br
+
+This option corresponds to the \-\-header\-title command line option of
+.BR genhtml .
+.br
+
+Default is "LCOV - coverage report".
+.PP
+
 .BR genhtml_dark_mode " ="
 .IR  0 | 1
 .IP