[LTP] [RFC] Remove [Description] subtitle from docparse

[LTP] [RFC] Remove [Description] subtitle from docparse

[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

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [RFC] Remove [Description] subtitle from docparse

[Andrea Cervesato via 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

On 1/31/25 10:15, Petr Vorel wrote:
> 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
>

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [RFC] Remove [Description] subtitle from docparse

[Petr Vorel]

Hi Andrea,

> 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 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

> Andrea

> On 1/31/25 10:15, Petr Vorel wrote:
> > 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/

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [RFC] Remove [Description] subtitle from docparse

[Andrea Cervesato via ltp]

On 1/31/25 11:34, Petr Vorel wrote:
> Hi Andrea,
>
>> 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.
>
>> 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.
> Kind regards,
> Petr
>
>> Andrea
>> On 1/31/25 10:15, Petr Vorel wrote:
>>> 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/
Andrea

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [RFC] Remove [Description] subtitle from docparse

[Cyril Hrubis]

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).

That part can be fixed with something as:

diff --git a/metadata/metaparse.c b/metadata/metaparse.c
index 2b96149dc..422604a2c 100644
--- a/metadata/metaparse.c
+++ b/metadata/metaparse.c
@@ -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);

> 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.

-- 
Cyril Hrubis
chrubis@suse.cz

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [RFC] Remove [Description] subtitle from docparse

[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).

> That part can be fixed with something as:

> diff --git a/metadata/metaparse.c b/metadata/metaparse.c
> index 2b96149dc..422604a2c 100644
> --- a/metadata/metaparse.c
> +++ b/metadata/metaparse.c
> @@ -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);

Sure, that could work as well.

> > 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

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [RFC] Remove [Description] subtitle from docparse

[Petr Vorel]

Hi Andrea,

> On 1/31/25 11:34, Petr Vorel wrote:
> > Hi Andrea,

> > > 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.

> > > 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.

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

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp