Merge pull request #4244 from masatake/scdoc

masatake · web-flow · commit 64829f42b7f3 · 2025-05-10T13:48:09.000+09:00
Scdoc: new parser
diff --git a/Tmain/line-regex-optscript.d/hello.ctags b/Tmain/line-regex-optscript.d/hello.ctags
@@ -28,4 +28,5 @@
 
 --regex-hello=/^end//{{
 	(hello) pstack
+	clear
 }}
diff --git a/Tmain/warn-garbage-on-ostack.d/exit-expected.txt b/Tmain/warn-garbage-on-ostack.d/exit-expected.txt
@@ -0,0 +1 @@
+0
diff --git a/Tmain/warn-garbage-on-ostack.d/garbage.ctags b/Tmain/warn-garbage-on-ostack.d/garbage.ctags
@@ -0,0 +1,7 @@
+--langdef=Garbage
+--map-Garbage=.garbage
+
+--regex-Garbage=/a//{{
+  /garbage0
+  (garbage1)
+}}
diff --git a/Tmain/warn-garbage-on-ostack.d/input.garbage b/Tmain/warn-garbage-on-ostack.d/input.garbage
@@ -0,0 +1 @@
+a
diff --git a/Tmain/warn-garbage-on-ostack.d/run.sh b/Tmain/warn-garbage-on-ostack.d/run.sh
@@ -0,0 +1,6 @@
+# Copyright: 2017 Masatake YAMATO
+# License: GPL-2
+
+CTAGS=$1
+
+$CTAGS --quiet --options=NONE --options=./garbage.ctags -o - input.garbage
diff --git a/Tmain/warn-garbage-on-ostack.d/stderr-expected.txt b/Tmain/warn-garbage-on-ostack.d/stderr-expected.txt
@@ -0,0 +1 @@
+ctags: Warning: [Garbage] 2 objects are left on the operand stack: input.garbage
diff --git a/Tmain/warn-garbage-on-ostack.d/stdout-expected.txt b/Tmain/warn-garbage-on-ostack.d/stdout-expected.txt
diff --git a/Units/parser-scdoc.r/end-with-subsection.d/args.ctags b/Units/parser-scdoc.r/end-with-subsection.d/args.ctags
@@ -0,0 +1,2 @@
+--sort=no
+--fields=+en
diff --git a/Units/parser-scdoc.r/end-with-subsection.d/expected.tags b/Units/parser-scdoc.r/end-with-subsection.d/expected.tags
@@ -0,0 +1,4 @@
+foo	input.scd	/^foo(1)$/;"	t	line:1	end:10
+a	input.scd	/^# a$/;"	s	line:6	title:foo	end:7
+c	input.scd	/^# c$/;"	s	line:8	title:foo	end:10
+b	input.scd	/^## b$/;"	S	line:10	section:foo""c	end:10
diff --git a/Units/parser-scdoc.r/end-with-subsection.d/input.scd b/Units/parser-scdoc.r/end-with-subsection.d/input.scd
@@ -0,0 +1,10 @@
+foo(1)
+
+## This one should not be extracted
+ because there is no section owns this.
+
+# a
+
+# c
+
+## b
diff --git a/Units/parser-scdoc.r/simple-scdoc.d/README b/Units/parser-scdoc.r/simple-scdoc.d/README
@@ -0,0 +1 @@
+input.md is taken from https://git.sr.ht/~sircmpwn/scdoc/tree/master/item/scdoc.5.scd .
diff --git a/Units/parser-scdoc.r/simple-scdoc.d/args.ctags b/Units/parser-scdoc.r/simple-scdoc.d/args.ctags
@@ -0,0 +1,2 @@
+--sort=no
+--fields=+ne
diff --git a/Units/parser-scdoc.r/simple-scdoc.d/expected.tags b/Units/parser-scdoc.r/simple-scdoc.d/expected.tags
@@ -0,0 +1,17 @@
+SCDOC	input.scd	/^SCDOC(5)$/;"	t	line:1	end:213
+NAME	input.scd	/^# NAME$/;"	s	line:3	title:SCDOC	end:6
+SYNTAX	input.scd	/^# SYNTAX$/;"	s	line:7	title:SCDOC	end:200
+Preamble	input.scd	/^## Preamble$/;"	S	line:11	section:SCDOC""SYNTAX	end:23
+Section headers	input.scd	/^## Section headers$/;"	S	line:24	section:SCDOC""SYNTAX	end:33
+Paragraphs	input.scd	/^## Paragraphs$/;"	S	line:34	section:SCDOC""SYNTAX	end:37
+Line breaks	input.scd	/^## Line breaks$/;"	S	line:38	section:SCDOC""SYNTAX	end:44
+Formatting	input.scd	/^## Formatting$/;"	S	line:45	section:SCDOC""SYNTAX	end:49
+Indentation	input.scd	/^## Indentation$/;"	S	line:50	section:SCDOC""SYNTAX	end:61
+Lists	input.scd	/^## Lists$/;"	S	line:62	section:SCDOC""SYNTAX	end:98
+Numbered lists	input.scd	/^## Numbered lists$/;"	S	line:99	section:SCDOC""SYNTAX	end:115
+Tables	input.scd	/^## Tables$/;"	S	line:116	section:SCDOC""SYNTAX	end:173
+Literal text	input.scd	/^## Literal text$/;"	S	line:174	section:SCDOC""SYNTAX	end:192
+Comments	input.scd	/^## Comments$/;"	S	line:193	section:SCDOC""SYNTAX	end:200
+CONVENTIONS	input.scd	/^# CONVENTIONS$/;"	s	line:201	title:SCDOC	end:204
+SEE ALSO	input.scd	/^# SEE ALSO$/;"	s	line:205	title:SCDOC	end:208
+AUTHORS	input.scd	/^# AUTHORS$/;"	s	line:209	title:SCDOC	end:213
diff --git a/Units/parser-scdoc.r/simple-scdoc.d/input.scd b/Units/parser-scdoc.r/simple-scdoc.d/input.scd
@@ -0,0 +1,213 @@
+SCDOC(5)
+
+# NAME
+
+scdoc - document format for writing manual pages
+
+# SYNTAX
+
+Input files must use the UTF-8 encoding.
+
+## Preamble
+
+Each scdoc file must begin with the following preamble:
+
+	_NAME_(_section_) ["left\_footer" ["center\_header"]]
+
+_NAME_ is the name of the man page you are writing, and _section_ is the section
+you're writing for (see _man_(1) for information on manual sections).
+
+_left\_footer_ and _center\_header_ are optional arguments which set the text
+positioned at those locations in the generated man page, and *must* be
+surrounded with double quotes.
+
+## Section headers
+
+Each section of your man page should begin with something similar to the
+following:
+
+	# HEADER NAME
+
+Subsection headers are also understood - use two hashes. Each header must have
+an empty line on either side.
+
+## Paragraphs
+
+Begin a new paragraph with an empty line.
+
+## Line breaks
+
+Insert a line break by ending a line with \+\+.
+
+The result looks++
+like this.
+
+## Formatting
+
+Text can be made *bold* or _underlined_ with asterisks and underscores: \*bold\*
+or \_underlined\_. Underscores in the_middle_of_words will be disregarded.
+
+## Indentation
+
+You may indent lines with tab characters (*\\t*) to indent them by 4 spaces in
+the output. Indented lines may not contain headers.
+
+	The result looks something like this.
+
+	You may use multiple lines and most _formatting_.
+
+Deindent to return to normal, or indent again to increase your indentation
+depth.
+
+## Lists
+
+You may start bulleted lists with dashes (-), like so:
+
+```
+- Item 1
+- Item 2
+	- Subitem 1
+	- Subitem 2
+- Item 3
+```
+
+The result looks like this:
+
+- Item 1
+- Item 2
+	- Subitem 1
+	- Subitem 2
+- Item 3
+
+You may also extend long entries onto another line by giving it the same indent
+level, plus two spaces. They will be rendered as a single list entry.
+
+```
+- Item 1 is pretty long so let's
+  break it up onto two lines
+- Item 2 is shorter
+	- But its children can go on
+	  for a while
+```
+
+- Item 1 is pretty long so let's
+  break it up onto two lines
+- Item 2 is shorter
+	- But its children can go on
+	  for a while
+
+## Numbered lists
+
+Numbered lists are similar to normal lists, but begin with periods (.) instead
+of dashes (-), like so:
+
+```
+. Item 1
+. Item 2
+. Item 3,
+  with multiple lines
+```
+
+. Item 1
+. Item 2
+. Item 3,
+  with multiple lines
+
+## Tables
+
+To begin a table, add an empty line followed by any number of rows.
+
+Each line of a table should start with | or : to start a new row or column
+respectively (or space to continue the previous cell on multiple lines),
+followed by [ or - or ] to align the contents to the left, center, or right,
+followed by a space and the contents of that cell. You may use a space instead
+of an alignment specifier to inherit the alignment of the same column in the
+previous row. Each row must have the same number of columns; empty columns are
+permitted.
+
+The first character of the first row is not limited to | and has special
+meaning. [ will produce a table with borders around each cell. | will produce a
+table with no borders. ] will produce a table with one border around the whole
+table.
+
+To conclude your table, add an empty line after the last row.
+
+```
+[[ *Foo*
+:- _Bar_
+:-
+|  *Row 1*
+:  Hello
+:] world!
+|  *Row 2*
+:  こんにちは
+:  世界
+   !
+```
+
+[[ *Foo*
+:- _Bar_
+:-
+|  *Row 1*
+:  Hello
+:] world!
+|  *Row 2*
+:  こんにちは
+:  世界
+   !
+
+You may also cause columns to expand to fill the available space with < (left
+align), = (center align), and > (right align), like so:
+
+```
+[[ *Normal column*
+:< Expanded column
+|  *Foo*
+:  Bar
+```
+
+[[ *Normal column*
+:< Expanded column
+|  *Foo*
+:  Bar
+
+## Literal text
+
+You may turn off scdoc formatting and output literal text with escape codes and
+literal blocks. Inserting a \\ into your source will cause the subsequent symbol
+to be treated as a literal and copied directly to the output. You may also make
+blocks of literal syntax like so:
+
+```
+\```
+_This formatting_ will *not* be interpreted by scdoc.
+\```
+```
+
+These blocks will be indented one level. Note that literal text is shown
+literally in the man viewer - that is, it's not a means for inserting your own
+roff macros into the output. Note that \\ is still interpreted within literal
+blocks, which for example can be useful to output \``` inside of a literal
+block.
+
+## Comments
+
+Lines beginning with ; and a space are ignored.
+
+```
+; This is a comment
+```
+
+# CONVENTIONS
+
+By convention, all scdoc documents should be hard wrapped at 80 columns.
+
+# SEE ALSO
+
+_scdoc_(1)
+
+# AUTHORS
+
+Maintained by Drew DeVault <sir@cmpwn.com>. Up-to-date sources can be found at
+https://git.sr.ht/~sircmpwn/scdoc and bugs/patches can be submitted by email to
+~sircmpwn/public-inbox@lists.sr.ht.
diff --git a/docs/news/HEAD.rst b/docs/news/HEAD.rst
@@ -45,6 +45,7 @@ New parsers
 * SELinuxIntefae *M4 based subparser*
 * SELinuxTypeEnforcement *optlib*
 * PythonEntryPoints *subparser*
+* Scdoc *optlib*
 
 Changes about parser specific kinds, roles, fields, and extras
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/main/lregex.c b/main/lregex.c
@@ -2242,6 +2242,12 @@ extern void notifyRegexInputStart (struct lregexControlBlock *lcb)
 extern void notifyRegexInputEnd (struct lregexControlBlock *lcb)
 {
 	scriptEvalHook (optvm, lcb, SCRIPT_HOOK_SEQUEL);
+	unsigned int garbage;
+	if ((garbage = opt_vm_ostack_count (optvm)) > 0)
+		error (WARNING, "[%s] %u objects are left on the operand stack: %s",
+			   getLanguageName (lcb->owner), garbage,
+			   getInputFileName ());
+
 	set_current_lcb (optvm, NULL);
 	opt_vm_clear (optvm, false);
 	opt_dict_clear (lcb->local_dict);
diff --git a/main/parsers_p.h b/main/parsers_p.h
@@ -176,6 +176,7 @@
 	ShParser, \
 	SlangParser, \
 	SmlParser, \
+	ScdocParser, \
 	SqlParser, \
 	SystemdUnitParser, \
 	SystemTapParser, \
diff --git a/optlib/scdoc.c b/optlib/scdoc.c
diff --git a/optlib/scdoc.ctags b/optlib/scdoc.ctags
diff --git a/source.mak b/source.mak
diff --git a/win32/ctags_vs2013.vcxproj b/win32/ctags_vs2013.vcxproj
diff --git a/win32/ctags_vs2013.vcxproj.filters b/win32/ctags_vs2013.vcxproj.filters

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+ctags: Warning: [Garbage] 2 objects are left on the operand stack: input.garbage`
-Original file line number
+Diff line change
@@ @@ -0,0 +1,10 @@ @@
 +foo(1)
++
 +## This one should not be extracted
 + because there is no section owns this.
++
 +# a
++
 +# c
++
 +## b