patch 9.0.0110: help tag generation picks up words in code examples

Problem:    Help tag generation picks up words in code examples.
Solution:   Skip over examples. (Carlo Teubner, closes #10813)

runtime/doc/doctags.c

@@ -21,6 +21,8 @@ main(int argc, char **argv)
 	char	*p1, *p2;
 	char	*p;
 	FILE	*fd;
+	int		len;
+	int		in_example;
 
 	if (argc <= 1)
 	{
@@ -37,22 +39,28 @@ main(int argc, char **argv)
 			fprintf(stderr, "Unable to open %s for reading\n", argv[0]);
 			continue;
 		}
+		in_example = 0;
 		while (fgets(line, LINELEN, fd) != NULL)
 		{
-			p1 = strchr(line, '*');				/* find first '*' */
+			if (in_example)
+			{
+				// skip over example; non-blank in first column ends example
+				if (strchr(" \t\n\r", line[0]) != NULL)
+					continue;
+				in_example = 0;
+			}
+			p1 = strchr(line, '*');				// find first '*'
 			while (p1 != NULL)
 			{
-				p2 = strchr(p1 + 1, '*');		/* find second '*' */
+				p2 = strchr(p1 + 1, '*');		// find second '*'
-				if (p2 != NULL && p2 > p1 + 1)	/* skip "*" and "**" */
+				if (p2 != NULL && p2 > p1 + 1)	// skip "*" and "**"
 				{
 					for (p = p1 + 1; p < p2; ++p)
 						if (*p == ' ' || *p == '\t' || *p == '|')
 							break;
-					/*
+					// Only accept a *tag* when it consists of valid
-					 * Only accept a *tag* when it consists of valid
+					// characters, there is white space before it and is
-					 * characters, there is white space before it and is
+					// followed by a white character or end-of-line.
-					 * followed by a white character or end-of-line.
-					 */
 					if (p == p2
 							&& (p1 == line || p1[-1] == ' ' || p1[-1] == '\t')
 								&& (strchr(" \t\n\r", p[1]) != NULL
@@ -63,18 +71,22 @@ main(int argc, char **argv)
 						printf("%s\t%s\t/*", p1, argv[0]);
 						while (*p1)
 						{
-							/* insert backslash before '\\' and '/' */
+							// insert backslash before '\\' and '/'
 							if (*p1 == '\\' || *p1 == '/')
 								putchar('\\');
 							putchar(*p1);
 							++p1;
 						}
 						printf("*\n");
-						p2 = strchr(p2 + 1, '*');		/* find next '*' */
+						p2 = strchr(p2 + 1, '*');		// find next '*'
 					}
 				}
 				p1 = p2;
 			}
+			len = strlen(line);
+			if ((len == 2 && strcmp(&line[len - 2], ">\n") == 0)
+					|| (len >= 3 && strcmp(&line[len - 3], " >\n") == 0))
+				in_example = 1;
 		}
 		fclose(fd);
 	}

src/help.c

@@ -960,6 +960,8 @@ helptags_one(
     int		utf8 = MAYBE;
     int		this_utf8;
     int		firstline;
+    int		in_example;
+    int		len;
     int		mix = FALSE;	// detected mixed encodings
 
     // Find all *.txt files.
@@ -1025,6 +1027,7 @@ helptags_one(
 	}
 	fname = files[fi] + dirlen + 1;
 
+	in_example = FALSE;
 	firstline = TRUE;
 	while (!vim_fgets(IObuff, IOSIZE, fd) && !got_int)
 	{
@@ -1059,6 +1062,13 @@ helptags_one(
 		}
 		firstline = FALSE;
 	    }
+	    if (in_example)
+	    {
+		// skip over example; a non-white in the first column ends it
+		if (vim_strchr((char_u *)" \t\n\r", IObuff[0]))
+		    continue;
+		in_example = FALSE;
+	    }
 	    p1 = vim_strchr(IObuff, '*');	// find first '*'
 	    while (p1 != NULL)
 	    {
@@ -1103,6 +1113,10 @@ helptags_one(
 		}
 		p1 = p2;
 	    }
+	    len = (int)STRLEN(IObuff);
+	    if ((len == 2 && STRCMP(&IObuff[len - 2], ">\n") == 0)
+		    || (len >= 3 && STRCMP(&IObuff[len - 3], " >\n") == 0))
+		in_example = TRUE;
 	    line_breakcheck();
 	}
 

src/testdir/test_help.vim

@@ -141,6 +141,13 @@ func Test_helptag_cmd()
   call assert_equal(["help-tags\ttags\t1"], readfile('Xdir/tags'))
   call delete('Xdir/tags')
 
+  " Test parsing tags
+  call writefile(['*tag1*', 'Example: >', '  *notag*', 'Example end: *tag2*'],
+    \ 'Xdir/a/doc/sample.txt')
+  helptags Xdir
+  call assert_equal(["tag1\ta/doc/sample.txt\t/*tag1*",
+                  \  "tag2\ta/doc/sample.txt\t/*tag2*"], readfile('Xdir/tags'))
+
   " Duplicate tags in the help file
   call writefile(['*tag1*', '*tag1*', '*tag2*'], 'Xdir/a/doc/sample.txt')
   call assert_fails('helptags Xdir', 'E154:')

src/version.c

@@ -735,6 +735,8 @@ static char *(features[]) =
 
 static int included_patches[] =
 {   /* Add new patch number below this line */
+/**/
+    110,
 /**/
     109,
 /**/