Remove [Description] subtitle from docparse
Hi,
Can we remove [Description] part from docparse documentation in tests? This is transformed into "Description" subtitle in resulted html/pdf.
1) It's not really needed (it's obvious that it's a description of the test)
2) Sometimes it's missing (inconsistency).
I would keep other subtitles (e.g. [Algorithm]), just remove the first one.
Kind regards,
Petr
Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
Hi Petr,
I'm currently working on parsing metadata in order to produce a tests list in the LTP documentation. I just replace "[Description]" with "**Description**". Same for "[Algorithm]".
I would keep the bold version tho, with the double star **.
Andrea
Quoted 13 lines · Petr Vorel
Hi,
Can we remove [Description] part from docparse documentation in tests? This is transformed into "Description" subtitle in resulted html/pdf.
1) It's not really needed (it's obvious that it's a description of the test)
2) Sometimes it's missing (inconsistency).I would keep other subtitles (e.g. [Algorithm]), just remove the first one.
Kind regards,
Petr
Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
Hi Andrea,
Quoted 4 lines
Hi Petr,
I'm currently working on parsing metadata in order to produce a tests list in the LTP documentation.
FYI I planned to work on it (announced in ML [1]), but since you started I stop working on it.
Quoted 4 lines
I just replace "[Description]" with "**Description**". Same for "[Algorithm]".
I would keep the bold version tho, with the double star **.
We talk about a different things. You about the conversion of the subtitles to the final documentation (previously was done in docparse/testinfo.pl, now you will do it in python).
But I'm suggesting to entirely remove subtitle "Description". It looks to me useless and some people don't add it thus docs looks inconsistent.
Kind regards,
Petr
Quoted 15 lines
Andrea
Quoted 12 lines · Petr Vorel
Hi,
Can we remove [Description] part from docparse documentation in tests? This is transformed into "Description" subtitle in resulted html/pdf.
1) It's not really needed (it's obvious that it's a description of the test)
2) Sometimes it's missing (inconsistency).I would keep other subtitles (e.g. [Algorithm]), just remove the first one.
Kind regards,
Petr
[1] https://lore.kernel.org/ltp/20241227073921.GB290415@pevik/
Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
Quoted 7 lines · Petr Vorel
Hi Andrea,
Quoted 3 lines
Hi Petr,
I'm currently working on parsing metadata in order to produce a tests list in the LTP documentation.FYI I planned to work on it (announced in ML [1]), but since you started I stop working on it.
I'm sorry, I didn't read carefully. The results will come out soon tho, I will send the patch-set soon.
Quoted 10 lines
Quoted 4 lines
I just replace "[Description]" with "**Description**". Same for "[Algorithm]".
I would keep the bold version tho, with the double star **.We talk about a different things. You about the conversion of the subtitles to the final documentation (previously was done in
docparse/testinfo.pl, now you will do it in python).But I'm suggesting to entirely remove subtitle "Description". It looks to me useless and some people don't add it thus docs looks inconsistent.
The thing is that there's not only [Description], but there's also [Algorithm]. Maybe we can think about the tests description as a whole RST code that will be injected inside the documentation website once it's published. In this way, conversion would be much easier.
Quoted 13 lines
Kind regards,
PetrQuoted 10 lines
Andrea
Quoted 8 lines · Petr Vorel
Hi,
Can we remove [Description] part from docparse documentation in tests? This is transformed into "Description" subtitle in resulted html/pdf.
1) It's not really needed (it's obvious that it's a description of the test)
2) Sometimes it's missing (inconsistency).
I would keep other subtitles (e.g. [Algorithm]), just remove the first one. Kind regards,
Petr
Quoted 1 line
[1] https://lore.kernel.org/ltp/20241227073921.GB290415@pevik/
Andrea
Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
Hi Andrea,
Quoted 10 lines · Petr Vorel
Quoted 7 lines
Hi Andrea,
Quoted 3 lines
Hi Petr,
I'm currently working on parsing metadata in order to produce a tests list in the LTP documentation.FYI I planned to work on it (announced in ML [1]), but since you started I stop working on it.
I'm sorry, I didn't read carefully. The results will come out soon tho, I will send the patch-set soon.
Not a big deal, just sometimes it might happen more people are implementing the same thing.
Quoted 7 lines
Quoted 6 lines
Quoted 3 lines
I just replace "[Description]" with "**Description**". Same for "[Algorithm]".
I would keep the bold version tho, with the double star **.We talk about a different things. You about the conversion of the subtitles to the final documentation (previously was done in
docparse/testinfo.pl, now you will do it in python).
Quoted 6 lines
Quoted 2 lines
But I'm suggesting to entirely remove subtitle "Description". It looks to me useless and some people don't add it thus docs looks inconsistent.
The thing is that there's not only [Description], but there's also [Algorithm]. Maybe we can think about the tests description as a whole RST code that will be injected inside the documentation website once it's published. In this way, conversion would be much easier.
As I wrote to Cyril:
The reason why suggested to remove it is that I don't see much information value in "Description" title. "Algorithm" has at least little bit of information value.
Besides these two we have only:
* [Prerequisites] (testcases/kernel/mem/ksm/ksm07.c)
* [Race Description] (testcases/kernel/syscalls/fork/fork13.c)
Kind regards,
Petr
Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
Hi!
Quoted 5 lines
Can we remove [Description] part from docparse documentation in tests? This is transformed into "Description" subtitle in resulted html/pdf.
1) It's not really needed (it's obvious that it's a description of the test)
2) Sometimes it's missing (inconsistency).
That part can be fixed with something as:
metadata/metaparse.c +8 -0
@@ -852,6 +852,14 @@ static struct data_node *parse_file(const char *fname)if (data_node_array_len (doc)) {data_node_hash_add (res,"doc" , doc); + +char *str = doc->array.array[0 ]->string.val; + +if (!strstr ("[Description]" , str)) { +fprintf (stderr,"%s: Missing [Description] in doc comment!\n" , fname); +exit (1 ); + } + found =1 ; }else {data_node_free (doc);
Quoted 1 line
I would keep other subtitles (e.g. [Algorithm]), just remove the first one.
I find it a bit inconsistent if we do it this way, but I guess either way is fine.
Signature · 5 lines
Cyril Hrubis [email protected] -- Mailing list info: https://lists.linux.it/listinfo/ltp
Quoted 18 lines
Hi!
Quoted 5 lines
Can we remove [Description] part from docparse documentation in tests? This is transformed into "Description" subtitle in resulted html/pdf.
1) It's not really needed (it's obvious that it's a description of the test)
2) Sometimes it's missing (inconsistency).That part can be fixed with something as:
metadata/metaparse.c +1
-0@@ -852,6 +852,14 @@ static struct data_node *parse_file(const char *fname)if (data_node_array_len (doc)) {data_node_hash_add (res,"doc" , doc); +
metadata/metaparse.c static struct data_node *parse_file(const char *fname) · line 865
Quoted 10 lines
metadata/metaparse.c +7
-0+char *str = doc->array.array[0 ]->string.val; + +if (!strstr ("[Description]" , str)) { +fprintf (stderr,"%s: Missing [Description] in doc comment!\n" , fname); +exit (1 ); + } + found =1 ; }else {data_node_free (doc);
Sure, that could work as well.
Quoted 4 lines
Quoted 1 line
I would keep other subtitles (e.g. [Algorithm]), just remove the first one.
I find it a bit inconsistent if we do it this way, but I guess either way is fine.
The reason why suggested to remove it is that I don't see much information value in "Description" title. "Algorithm" has at least little bit of information value.
Besides these two we have only:
* [Prerequisites] (testcases/kernel/mem/ksm/ksm07.c)
* [Race Description] (testcases/kernel/syscalls/fork/fork13.c)
Kind regards,
Petr
Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp