Commit Graph

16 Commits

Author SHA1 Message Date
Mauro Carvalho Chehab c339665666 docs-rst: parse-headers.pl: cleanup the documentation
Keeping both rst and in-file documentation in sync can be harsh.

So, simplify the script's internal documntation to a bare minimum,
and add a mention to the ReST file with its full documentation.

This way, a quick help is still available at the command line,
while the complete one is maintained at the ReST format.

As we won't be using pad2rst anymore, do a cleanup at the ReST
file.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-30 17:08:09 -07:00
Mauro Carvalho Chehab 327f5a754a parse-headers.pl: add documentation for this script
Provide a man page for parse-headers.pl, describing
how to use it.

The documentation on ReST format was generated via pod2rst:
	http://search.cpan.org/~dowens/Pod-POM-View-Restructured-0.02/bin/pod2rst

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-19 10:22:08 -07:00
Mauro Carvalho Chehab 22c4003364 [media] docs-rst: parse-headers.pl: use the C domain for cross-references
Instead of keep using the normal reference, move to the C
domain ones. Using C domains everywhere will allow
cross-references between kAPI and uAPI docs.

Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-09-09 09:20:27 -03:00
Mauro Carvalho Chehab bcec7c218d [media] docs-rst: parse-headers.pl: make debug a command line option
Add a parser for the --debug option, in order to allow
seeing what the parser is doing.

Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-09-09 09:20:06 -03:00
Mauro Carvalho Chehab 999d998eee docs-rst: parse-heraders.pl: escape LaTeX characters
Let's escape the LaTeX characters, to avoid troubles when
outputing them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-18 16:42:07 -06:00
Mauro Carvalho Chehab fb6fc6c9ac doc-rst: parse-headers: remove trailing spaces
The function that replace references add a "\ " at the end of
references, to avoid the ReST markup parser to not identify
them as references. That works fine except for the end of lines,
as a sequence of { '\', ' ', '\n' } characters makes Sphinx
to ignore the end of line. So, strip those escape/spaces at the
end of lines.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-09 09:42:31 -03:00
Mauro Carvalho Chehab 153234c47c doc-rst: parse-headers: don't do substituition references
Add one extra escape character to avoid those warnings:
	Documentation/linux_tv/videodev2.h.rst:6: WARNING: Inline substitution_reference start-string without end-string.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-07 15:13:17 -03:00
Mauro Carvalho Chehab 526b884831 doc-rst: parse-headers: add an option to ignore enum symbols
At videodev2.h, we have hundreds of symbols that don't
currently have a reference yet. Let's ignore for how, while
we don't improve those cross-refs.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-07 15:13:07 -03:00
Mauro Carvalho Chehab 034e6c8e72 doc-rst: parse-headers: better handle comments at the source code
We should not let comments to mangle with the symbols
parsing. Unfortunately, videodev2.h has lots of those
in the middle of enums and structs. So, we need to improve
our parser to discard them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-07 15:12:48 -03:00
Mauro Carvalho Chehab 4ff916a0c9 doc-rst: parse-headers: fix multiline typedef handler
The typedef handler should do two things to be generic:
  1) parse typedef enums;
  2) accept both possible syntaxes:
	 typedef struct foo { .. } foo_t;
	 typedef struct { .. } foo_t;

Unfortunately, this is needed to parse some legacy DVB
files, like dvb/audio.h.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-07 08:12:57 -03:00
Mauro Carvalho Chehab 6c4c7dadb4 doc-rst: parse-headers: better handle typedefs
When typedef is used on its multiline format, we need to
also parse enum and struct in the same line.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-07 07:22:20 -03:00
Mauro Carvalho Chehab 9c80c74563 doc-rst: parse-headers: be more formal about the valid symbols
Be more formal about the valid symbols that are expected by
the parser, to match what c language expects.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-07 07:08:32 -03:00
Mauro Carvalho Chehab 9afe51129b doc-rst: fix parsing comments and '{' on a separate line
The dmx.h header has two things that causes the parser to
break while handling enums:
 per-header enums and the '{' starts on a new line

Both makes the parser to get lexical marks to be detected
as if they were symbols.

Fix it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-07 06:54:00 -03:00
Mauro Carvalho Chehab 7d95fa8d66 doc-dst: parse-headers: highlight deprecated comments
When something is deprecated, highlight it, as we want it
to be clearer to the reader.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-07 06:36:46 -03:00
Mauro Carvalho Chehab 6fe79d1ede doc-rst: parse-headers: improve delimiters to detect symbols
As we had to escape the symbols for the ReST markup to not do
the wrong thing, the logic to discover start/end of strings
are not trivial. Improve the end delimiter detection, in order
to highlight more occurrences of the strings.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-07 06:36:46 -03:00
Mauro Carvalho Chehab dabf8be33b doc-rst: add parse-headers.pl script
This script parses a header file and converts it into a
parsed-literal block, creating references for ioctls,
defines, typedefs, enums and structs.

It also allow an external file to modify the rules, in
order to fix the expressions.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-07 05:53:06 -03:00