This is the mail archive of the
gdb@sourceware.org
mailing list for the GDB project.
Re: A new strategy for internals documentation
- From: Doug Evans <dje at google dot com>
- To: Eli Zaretskii <eliz at gnu dot org>
- Cc: Stan Shebs <stanshebs at earthlink dot net>, gdb <gdb at sourceware dot org>
- Date: Thu, 8 Aug 2013 14:07:51 -0700
- Subject: Re: A new strategy for internals documentation
- References: <5201781A dot 3000607 at earthlink dot net> <83k3jyunt8 dot fsf at gnu dot org> <5202A6D6 dot 8090908 at earthlink dot net> <83li4ct7ot dot fsf at gnu dot org>
On Thu, Aug 8, 2013 at 10:26 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Wed, 07 Aug 2013 12:58:14 -0700
>> From: Stan Shebs <stanshebs@earthlink.net>
>> CC: gdb@sourceware.org
>>
>> > So how just declaring gdbint.texinfo dead and deleting it altogether?
>>
>> Isn't that going to be the end state of what I'm proposing? :-) I just
>> added a path to conserve any bits that seem useful.
>
> My way is faster and easier.
Possibly alright, but what final result do we want?
[What are we working towards?]
>> People do want internals documentation, we hear grumbles about it on a
>> weekly basis.
>
> The grumbles come from people other than those who can provide the
> documentation. And the latter don't think we have a problem in the
> first place.
If the latter includes me I disagree.
[I think the latter includes me, IIUC, but I could be wrong.]
>> >> *** Migration of gdbint.texinfo to wiki
>> >
>> > Wiki is a bad idea, because there's virtually no control on the
>> > quality of the information there.
>>
>> That's true now, but I don't think I've heard of anybody being misled by
>> poor information on the GDB wiki.
>
> Again, if we don't care about the documentation, then of course we
> shouldn't care about poor information. If we do care, then wiki is a
> way to waste resources at best.
I disagree (that the wiki is a way to waste resources at best).
>> > AFAIK, Doxygen cannot generate an Info manual, only HTML. If so, this
>> > would be a serious downside that you don't mention.
>>
>> Hmm, I'm perhaps prejudiced since I haven't looked at any info file in
>> probably a decade. Are many people using them still?
>
> I do, quite a lot. Besides, Info is the official format of GNU
> documentation, you will have hard time convincing the FSF to demote an
> existing manual.
>
>> > If we want to keep the documentation in the sources, why not use the
>> > same system as libiberty?
>>
>> It's plausible, but idiosyncratic. How much development does it get,
>> vs Doxygen?
>
> Why do you need development for comments?
He's referring to development of the comment->doc generator.
[right?]
>> > Not having a review process for documentation is an "upside"
>> > because?...
>>
>> I think it's time-consuming overkill for tutorials and howtos. An
>> underlying implicit goal here is to encourage contribution, not think of
>> ways to chase people away.
>
> The net result will be that the documentation will be unreadable. Not
> everybody who writes good code can write good documentation.
OTOH, It's easier to improve documentation over time.
[it's more important to get code right sooner than later]