Mailing List Archive: [RFC] New category: dev-doc (?)

[RFC] New category: dev-doc (?)

mgorny at gentoo

Jan 7, 2024, 8:39 AM

Post #1 of 6 (70 views)

Hi,

Here's another idea, a new dev-doc category (though I suppose we could
try to find a better name), dedicated to:

Tools to generate, convert, view and process documentation.

This is notably meant to move software out of app-doc/ which is
specifically dedicated to "documentation collections". Candidates:

app-doc/NaturalDocs
app-doc/doxygen
app-doc/halibut
app-doc/psmark
app-doc/xmltoman
app-doc/zeal
app-text/mandoc
app-text/texi2html
app-text/xchm
app-text/xml2rfc
app-text/xmlto
dev-util/gi-docgen
dev-util/gtk-doc
dev-util/source-highlight
sys-apps/man-db
sys-apps/texinfo

--
Best regards,
Micha? Górny

Re: [RFC] New category: dev-doc (?) [ In reply to ]

Jan 7, 2024, 8:58 AM

Post #2 of 6 (70 views)

>>>>> On Sun, 07 Jan 2024, Micha? Górny wrote:

> Here's another idea, a new dev-doc category (though I suppose we could
> try to find a better name), dedicated to:

> Tools to generate, convert, view and process documentation.

> This is notably meant to move software out of app-doc/ which is
> specifically dedicated to "documentation collections". Candidates:

> app-doc/NaturalDocs
> app-doc/doxygen
> app-doc/halibut
> app-doc/psmark
> app-doc/xmltoman
> app-doc/zeal
> app-text/mandoc
> app-text/texi2html
> app-text/xchm
> app-text/xml2rfc
> app-text/xmlto

I cannot really see a delineation between app-text and app-doc.

For example, packages like psmark, xmlto, or even texi2html are general
format manipulation/conversion tools and IMHO app-text is the right
category for them. Also, why would you keep pandoc and manpager in
app-text but move xmlto and mandoc out of it?

> dev-util/gi-docgen
> dev-util/gtk-doc
> dev-util/source-highlight
> sys-apps/man-db
> sys-apps/texinfo

Re: [RFC] New category: dev-doc (?) [ In reply to ]

Jan 7, 2024, 9:03 AM

Post #3 of 6 (70 views)

>>>>> On Sun, 07 Jan 2024, Ulrich Mueller wrote:

> I cannot really see a delineation between app-text and app-doc.

Sorry, this should read "between app-text and dev-doc", of course.

Re: [RFC] New category: dev-doc (?) [ In reply to ]

mgorny at gentoo

Jan 7, 2024, 10:26 AM

Post #4 of 6 (70 views)

On Sun, 2024-01-07 at 17:58 +0100, Ulrich Mueller wrote:
> > > > > > On Sun, 07 Jan 2024, Micha? Górny wrote:
>
> > Here's another idea, a new dev-doc category (though I suppose we could
> > try to find a better name), dedicated to:
>
> > Tools to generate, convert, view and process documentation.
>
> > This is notably meant to move software out of app-doc/ which is
> > specifically dedicated to "documentation collections". Candidates:
>
> > app-doc/NaturalDocs
> > app-doc/doxygen
> > app-doc/halibut
> > app-doc/psmark
> > app-doc/xmltoman
> > app-doc/zeal
> > app-text/mandoc
> > app-text/texi2html
> > app-text/xchm
> > app-text/xml2rfc
> > app-text/xmlto
>
> I cannot really see a delineation between app-text and app-doc.
>
> For example, packages like psmark, xmlto, or even texi2html are general
> format manipulation/conversion tools and IMHO app-text is the right
> category for them. Also, why would you keep pandoc and manpager in
> app-text but move xmlto and mandoc out of it?
>

It's a bit blurry. My original idea was to keep app-text/ for general-
purpose text tools (like text editors), while make dev-doc/ focused on
formats specific to documentation (like code documentation, manpages).

--
Best regards,
Micha? Górny

Re: [RFC] New category: dev-doc (?) [ In reply to ]

Jan 7, 2024, 10:51 PM

Post #5 of 6 (67 views)

>>>>> On Sun, 07 Jan 2024, Micha? Górny wrote:

> On Sun, 2024-01-07 at 17:58 +0100, Ulrich Mueller wrote:
>> I cannot really see a delineation between app-text and [dev]-doc.
>>
>> For example, packages like psmark, xmlto, or even texi2html are general
>> format manipulation/conversion tools and IMHO app-text is the right
>> category for them. Also, why would you keep pandoc and manpager in
>> app-text but move xmlto and mandoc out of it?

> It's a bit blurry. My original idea was to keep app-text/ for general-
> purpose text tools (like text editors), while make dev-doc/ focused on
> formats specific to documentation (like code documentation, manpages).

We already have app-editors for text editors. For the rest, it seems
very blurry indeed and would leave us with (IMHO too many) borderline
cases.

You certainly have a point that document processing tools are misplaced
in app-doc. Maybe just move them to app-text, which would be a more
minimal change?

Ulrich

Re: [RFC] New category: dev-doc (?) [ In reply to ]

mgorny at gentoo

Jan 8, 2024, 5:44 AM

Post #6 of 6 (66 views)

On Mon, 2024-01-08 at 07:51 +0100, Ulrich Mueller wrote:
> > > > > > On Sun, 07 Jan 2024, Micha? Górny wrote:
>
> > On Sun, 2024-01-07 at 17:58 +0100, Ulrich Mueller wrote:
> > > I cannot really see a delineation between app-text and [dev]-doc.
> > >
> > > For example, packages like psmark, xmlto, or even texi2html are general
> > > format manipulation/conversion tools and IMHO app-text is the right
> > > category for them. Also, why would you keep pandoc and manpager in
> > > app-text but move xmlto and mandoc out of it?
>
> > It's a bit blurry. My original idea was to keep app-text/ for general-
> > purpose text tools (like text editors), while make dev-doc/ focused on
> > formats specific to documentation (like code documentation, manpages).
>
> We already have app-editors for text editors. For the rest, it seems
> very blurry indeed and would leave us with (IMHO too many) borderline
> cases.
>
> You certainly have a point that document processing tools are misplaced
> in app-doc. Maybe just move them to app-text, which would be a more
> minimal change?
>

I suppose that would work for me. I'll wait a few more days, though, to
make sure we won't end up moving them twice over a short period.

--
Best regards,
Micha? Górny