* gdb.texinfo is getting too big @ 2013-10-14 20:06 Doug Evans 2013-10-14 20:10 ` Eli Zaretskii 0 siblings, 1 reply; 14+ messages in thread From: Doug Evans @ 2013-10-14 20:06 UTC (permalink / raw) To: Eli Zaretskii, gdb-patches, Stan Shebs Hi. What do people think about splitting up gdb.texinfo? I don't have a strong preference regarding how, I just know it'd be easier for me to work with if topics like the python scripting were in their own file. Stan reminded me that gcc docs are split up. Something like splitting the gdb docs up per chapter would "work for me". [The result would still be *one* manual, but editing and maintaining it would, for me, be easier.] Thoughts? Suggestions? ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: gdb.texinfo is getting too big 2013-10-14 20:06 gdb.texinfo is getting too big Doug Evans @ 2013-10-14 20:10 ` Eli Zaretskii 2013-10-14 20:26 ` Doug Evans 0 siblings, 1 reply; 14+ messages in thread From: Eli Zaretskii @ 2013-10-14 20:10 UTC (permalink / raw) To: Doug Evans; +Cc: gdb-patches, stan > Date: Mon, 14 Oct 2013 13:06:09 -0700 > From: Doug Evans <dje@google.com> > > What do people think about splitting up gdb.texinfo? Fine with me. ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: gdb.texinfo is getting too big 2013-10-14 20:10 ` Eli Zaretskii @ 2013-10-14 20:26 ` Doug Evans 2013-10-15 2:44 ` Eli Zaretskii 0 siblings, 1 reply; 14+ messages in thread From: Doug Evans @ 2013-10-14 20:26 UTC (permalink / raw) To: Eli Zaretskii; +Cc: gdb-patches, Stan Shebs On Mon, Oct 14, 2013 at 1:10 PM, Eli Zaretskii <eliz@gnu.org> wrote: >> Date: Mon, 14 Oct 2013 13:06:09 -0700 >> From: Doug Evans <dje@google.com> >> >> What do people think about splitting up gdb.texinfo? > > Fine with me. Cool. Next question: Any strong preference for how? I suggested splitting up by chapter, and that's fine with me, but before I do all that work, IWBN to get pre-approval for at least the general idea. I count > 40. Is there a less granular split people want? [Keeping the split mechanical, by something like chapter, is easy. Otherwise a discussion could drag on ...] ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: gdb.texinfo is getting too big 2013-10-14 20:26 ` Doug Evans @ 2013-10-15 2:44 ` Eli Zaretskii 2013-10-16 18:55 ` Doug Evans 2013-10-16 20:07 ` Stan Shebs 0 siblings, 2 replies; 14+ messages in thread From: Eli Zaretskii @ 2013-10-15 2:44 UTC (permalink / raw) To: Doug Evans; +Cc: gdb-patches, stan > Date: Mon, 14 Oct 2013 13:25:59 -0700 > From: Doug Evans <dje@google.com> > Cc: gdb-patches <gdb-patches@sourceware.org>, Stan Shebs <stan@codesourcery.com> > > Next question: Any strong preference for how? > I suggested splitting up by chapter, and that's fine with me, but > before I do all that work, IWBN to get pre-approval for at least the > general idea. > I count > 40. > Is there a less granular split people want? No, it's too fine-grained. 40 files is too much, IMO. It is better to group several consecutive chapters into a single file. > [Keeping the split mechanical, by something like chapter, is easy. > Otherwise a discussion could drag on ...] Well, you started it ;-) ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: gdb.texinfo is getting too big 2013-10-15 2:44 ` Eli Zaretskii @ 2013-10-16 18:55 ` Doug Evans 2013-10-16 19:01 ` Eli Zaretskii 2013-10-16 20:07 ` Stan Shebs 1 sibling, 1 reply; 14+ messages in thread From: Doug Evans @ 2013-10-16 18:55 UTC (permalink / raw) To: Eli Zaretskii; +Cc: gdb-patches, Stan Shebs On Mon, Oct 14, 2013 at 7:44 PM, Eli Zaretskii <eliz@gnu.org> wrote: >> Date: Mon, 14 Oct 2013 13:25:59 -0700 >> From: Doug Evans <dje@google.com> >> Cc: gdb-patches <gdb-patches@sourceware.org>, Stan Shebs <stan@codesourcery.com> >> >> Next question: Any strong preference for how? >> I suggested splitting up by chapter, and that's fine with me, but >> before I do all that work, IWBN to get pre-approval for at least the >> general idea. >> I count > 40. >> Is there a less granular split people want? > > No, it's too fine-grained. 40 files is too much, IMO. It is better > to group several consecutive chapters into a single file. > >> [Keeping the split mechanical, by something like chapter, is easy. >> Otherwise a discussion could drag on ...] > > Well, you started it ;-) The worry I have with any kind of grouping not based on the doc itself is that it introduces a potentially non-intuitive layer that someone has to learn in order to know which file contains the text one wants to edit. grep will find it of course, but if one is having to grep too much, would that be a problem? ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: gdb.texinfo is getting too big 2013-10-16 18:55 ` Doug Evans @ 2013-10-16 19:01 ` Eli Zaretskii 2013-10-16 19:52 ` Pedro Alves 0 siblings, 1 reply; 14+ messages in thread From: Eli Zaretskii @ 2013-10-16 19:01 UTC (permalink / raw) To: Doug Evans; +Cc: gdb-patches, stan > Date: Wed, 16 Oct 2013 11:55:00 -0700 > From: Doug Evans <dje@google.com> > Cc: gdb-patches <gdb-patches@sourceware.org>, Stan Shebs <stan@codesourcery.com> > > The worry I have with any kind of grouping not based on the doc itself > is that it introduces a potentially non-intuitive layer that someone > has to learn in order to know which file contains the text one wants > to edit. grep will find it of course, but if one is having to grep > too much, would that be a problem? Emacs uses this scheme, and I didn't hear any complaints, FWIW. ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: gdb.texinfo is getting too big 2013-10-16 19:01 ` Eli Zaretskii @ 2013-10-16 19:52 ` Pedro Alves 2013-10-16 20:06 ` Eli Zaretskii 0 siblings, 1 reply; 14+ messages in thread From: Pedro Alves @ 2013-10-16 19:52 UTC (permalink / raw) To: Eli Zaretskii; +Cc: Doug Evans, gdb-patches, stan On 10/16/2013 08:01 PM, Eli Zaretskii wrote: >> Date: Wed, 16 Oct 2013 11:55:00 -0700 >> From: Doug Evans <dje@google.com> >> Cc: gdb-patches <gdb-patches@sourceware.org>, Stan Shebs <stan@codesourcery.com> >> >> The worry I have with any kind of grouping not based on the doc itself >> is that it introduces a potentially non-intuitive layer that someone >> has to learn in order to know which file contains the text one wants >> to edit. grep will find it of course, but if one is having to grep >> too much, would that be a problem? > > Emacs uses this scheme, and I didn't hear any complaints, FWIW. Maybe it'd be easier to think in terms of things that would make sense to split out of the main file. E.g., the RSP chapter is useful for GDB and stub developers, but not for regular users -- split that one out. Python scripting API stuff is useful for advanced users that want to extend GDB, but it's not really the same class of manual as the other chapters, so split that one out as another file too. MI is useful for frontend writers, not for regular users, so out it goes too. Whatever other identifiable logic units we find, split them out. Then I suspect we'll end up with the core manual for regular users that describes GDB's main features/CLI/commands, and it'll be lean enough to be manageable. -- Pedro Alves ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: gdb.texinfo is getting too big 2013-10-16 19:52 ` Pedro Alves @ 2013-10-16 20:06 ` Eli Zaretskii 2013-10-16 20:10 ` Paul_Koning 2013-10-16 21:29 ` Pedro Alves 0 siblings, 2 replies; 14+ messages in thread From: Eli Zaretskii @ 2013-10-16 20:06 UTC (permalink / raw) To: Pedro Alves; +Cc: dje, gdb-patches, stan > Date: Wed, 16 Oct 2013 20:52:41 +0100 > From: Pedro Alves <palves@redhat.com> > CC: Doug Evans <dje@google.com>, gdb-patches@sourceware.org, > stan@codesourcery.com > > Maybe it'd be easier to think in terms of things that would make > sense to split out of the main file. E.g., the RSP chapter is useful > for GDB and stub developers, but not for regular users -- split that > one out. Python scripting API stuff is useful for advanced users > that want to extend GDB, but it's not really the same class of manual > as the other chapters, so split that one out as another file too. > MI is useful for frontend writers, not for regular users, so out it > goes too. Whatever other identifiable logic units we find, split > them out. Then I suspect we'll end up with the core manual for > regular users that describes GDB's main features/CLI/commands, > and it'll be lean enough to be manageable. You are talking about splitting the manual, whereas Doug was talking about splitting the sources while keeping a single manual as output. I'm not sure I see a good reason to split the manual. For starters, the size of that doesn't hurt as much as the size of the source file when you need to edit it. ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: gdb.texinfo is getting too big 2013-10-16 20:06 ` Eli Zaretskii @ 2013-10-16 20:10 ` Paul_Koning 2013-10-16 21:41 ` Pedro Alves 2013-10-16 21:29 ` Pedro Alves 1 sibling, 1 reply; 14+ messages in thread From: Paul_Koning @ 2013-10-16 20:10 UTC (permalink / raw) To: eliz; +Cc: palves, dje, gdb-patches, stan On Oct 16, 2013, at 4:06 PM, Eli Zaretskii <eliz@gnu.org> wrote: >> Date: Wed, 16 Oct 2013 20:52:41 +0100 >> From: Pedro Alves <palves@redhat.com> >> CC: Doug Evans <dje@google.com>, gdb-patches@sourceware.org, >> stan@codesourcery.com >> >> Maybe it'd be easier to think in terms of things that would make >> sense to split out of the main file. E.g., the RSP chapter is useful >> for GDB and stub developers, but not for regular users -- split that >> one out. Python scripting API stuff is useful for advanced users >> that want to extend GDB, but it's not really the same class of manual >> as the other chapters, so split that one out as another file too. >> MI is useful for frontend writers, not for regular users, so out it >> goes too. Whatever other identifiable logic units we find, split >> them out. Then I suspect we'll end up with the core manual for >> regular users that describes GDB's main features/CLI/commands, >> and it'll be lean enough to be manageable. > > You are talking about splitting the manual, whereas Doug was talking > about splitting the sources while keeping a single manual as output. > > I'm not sure I see a good reason to split the manual. For starters, > the size of that doesn't hurt as much as the size of the source file > when you need to edit it. Agreed. There are plenty of examples of large manuals (GCC, GCCint, Emacs). Divide them into as many source files as is convenient, that doesn't bother any user. But having the manual (what users read) split into multiple parts is not a good change. If we ever hit 5000 pages I might change my tune, but no GDB documentation is even close to that big. paul ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: gdb.texinfo is getting too big 2013-10-16 20:10 ` Paul_Koning @ 2013-10-16 21:41 ` Pedro Alves 2013-11-01 19:37 ` Doug Evans 0 siblings, 1 reply; 14+ messages in thread From: Pedro Alves @ 2013-10-16 21:41 UTC (permalink / raw) To: Paul_Koning; +Cc: eliz, dje, gdb-patches, stan On 10/16/2013 09:10 PM, Paul_Koning@Dell.com wrote: > > On Oct 16, 2013, at 4:06 PM, Eli Zaretskii <eliz@gnu.org> wrote: > >>> Date: Wed, 16 Oct 2013 20:52:41 +0100 >>> From: Pedro Alves <palves@redhat.com> >>> CC: Doug Evans <dje@google.com>, gdb-patches@sourceware.org, >>> stan@codesourcery.com >>> >>> Maybe it'd be easier to think in terms of things that would make >>> sense to split out of the main file. E.g., the RSP chapter is useful >>> for GDB and stub developers, but not for regular users -- split that >>> one out. Python scripting API stuff is useful for advanced users >>> that want to extend GDB, but it's not really the same class of manual >>> as the other chapters, so split that one out as another file too. >>> MI is useful for frontend writers, not for regular users, so out it >>> goes too. Whatever other identifiable logic units we find, split >>> them out. Then I suspect we'll end up with the core manual for >>> regular users that describes GDB's main features/CLI/commands, >>> and it'll be lean enough to be manageable. >> >> You are talking about splitting the manual, whereas Doug was talking >> about splitting the sources while keeping a single manual as output. >> >> I'm not sure I see a good reason to split the manual. For starters, >> the size of that doesn't hurt as much as the size of the source file >> when you need to edit it. > > Agreed. There are plenty of examples of large manuals (GCC, GCCint, Emacs). Divide them into as many source files as is convenient, that doesn't bother any user. But having the manual (what users read) split into multiple parts is not a good change. > > If we ever hit 5000 pages I might change my tune, but no GDB documentation is even close to that big. I was not suggesting to split the resulting produced manual. Sorry if I wasn't clear. I guess I should have said "core file" where it reads "core manual". I don't see a need to for a user visible split either. My response was in response to "The worry I have with any kind of grouping not based on the doc itself is that it introduces a potentially non-intuitive layer that someone has to learn in order to know which file contains the text one wants to edit." and I was presenting a rationale for splitting around logical grouping units. -- Pedro Alves ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: gdb.texinfo is getting too big 2013-10-16 21:41 ` Pedro Alves @ 2013-11-01 19:37 ` Doug Evans 2013-11-01 19:57 ` Eli Zaretskii 0 siblings, 1 reply; 14+ messages in thread From: Doug Evans @ 2013-11-01 19:37 UTC (permalink / raw) To: Pedro Alves; +Cc: Paul Koning, Eli Zaretskii, gdb-patches, Stan Shebs On Wed, Oct 16, 2013 at 2:39 PM, Pedro Alves <palves@redhat.com> wrote: > On 10/16/2013 09:10 PM, Paul_Koning@Dell.com wrote: >> >> On Oct 16, 2013, at 4:06 PM, Eli Zaretskii <eliz@gnu.org> wrote: >> >>>> Date: Wed, 16 Oct 2013 20:52:41 +0100 >>>> From: Pedro Alves <palves@redhat.com> >>>> CC: Doug Evans <dje@google.com>, gdb-patches@sourceware.org, >>>> stan@codesourcery.com >>>> >>>> Maybe it'd be easier to think in terms of things that would make >>>> sense to split out of the main file. E.g., the RSP chapter is useful >>>> for GDB and stub developers, but not for regular users -- split that >>>> one out. Python scripting API stuff is useful for advanced users >>>> that want to extend GDB, but it's not really the same class of manual >>>> as the other chapters, so split that one out as another file too. >>>> MI is useful for frontend writers, not for regular users, so out it >>>> goes too. Whatever other identifiable logic units we find, split >>>> them out. Then I suspect we'll end up with the core manual for >>>> regular users that describes GDB's main features/CLI/commands, >>>> and it'll be lean enough to be manageable. >>> >>> You are talking about splitting the manual, whereas Doug was talking >>> about splitting the sources while keeping a single manual as output. >>> >>> I'm not sure I see a good reason to split the manual. For starters, >>> the size of that doesn't hurt as much as the size of the source file >>> when you need to edit it. >> >> Agreed. There are plenty of examples of large manuals (GCC, GCCint, Emacs). Divide them into as many source files as is convenient, that doesn't bother any user. But having the manual (what users read) split into multiple parts is not a good change. >> >> If we ever hit 5000 pages I might change my tune, but no GDB documentation is even close to that big. > > I was not suggesting to split the resulting produced manual. > Sorry if I wasn't clear. I guess I should have said "core file" > where it reads "core manual". I don't see a need to for > a user visible split either. My response was in response to > > "The worry I have with any kind of grouping not based on the doc itself > is that it introduces a potentially non-intuitive layer that someone > has to learn in order to know which file contains the text one wants > to edit." > > and I was presenting a rationale for splitting around logical > grouping units. If people are ok with logical grouping units it's fine with me. One fear I have is a protracted discussion on the groupings. I do like the idea of splitting out pieces that are easy to split out. E.g., RSP, Python, maybe a few others. How about starting with that? ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: gdb.texinfo is getting too big 2013-11-01 19:37 ` Doug Evans @ 2013-11-01 19:57 ` Eli Zaretskii 0 siblings, 0 replies; 14+ messages in thread From: Eli Zaretskii @ 2013-11-01 19:57 UTC (permalink / raw) To: Doug Evans; +Cc: palves, Paul_Koning, gdb-patches, stan > Date: Fri, 1 Nov 2013 12:37:53 -0700 > From: Doug Evans <dje@google.com> > Cc: Paul Koning <Paul_Koning@dell.com>, Eli Zaretskii <eliz@gnu.org>, > gdb-patches <gdb-patches@sourceware.org>, Stan Shebs <stan@codesourcery.com> > > If people are ok with logical grouping units it's fine with me. > One fear I have is a protracted discussion on the groupings. > > I do like the idea of splitting out pieces that are easy to split out. > E.g., RSP, Python, maybe a few others. > > How about starting with that? Go for it. ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: gdb.texinfo is getting too big 2013-10-16 20:06 ` Eli Zaretskii 2013-10-16 20:10 ` Paul_Koning @ 2013-10-16 21:29 ` Pedro Alves 1 sibling, 0 replies; 14+ messages in thread From: Pedro Alves @ 2013-10-16 21:29 UTC (permalink / raw) To: Eli Zaretskii; +Cc: dje, gdb-patches, stan On 10/16/2013 09:06 PM, Eli Zaretskii wrote: > You are talking about splitting the manual. I actually wasn't. But I was applying the same rationale as if I was. > whereas Doug was talking > about splitting the sources while keeping a single manual as output. -- Pedro Alves ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: gdb.texinfo is getting too big 2013-10-15 2:44 ` Eli Zaretskii 2013-10-16 18:55 ` Doug Evans @ 2013-10-16 20:07 ` Stan Shebs 1 sibling, 0 replies; 14+ messages in thread From: Stan Shebs @ 2013-10-16 20:07 UTC (permalink / raw) To: gdb-patches On 10/14/13 7:44 PM, Eli Zaretskii wrote: >> Date: Mon, 14 Oct 2013 13:25:59 -0700 >> From: Doug Evans <dje@google.com> >> Cc: gdb-patches <gdb-patches@sourceware.org>, Stan Shebs <stan@codesourcery.com> >> >> Next question: Any strong preference for how? >> I suggested splitting up by chapter, and that's fine with me, but >> before I do all that work, IWBN to get pre-approval for at least the >> general idea. >> I count > 40. >> Is there a less granular split people want? > > No, it's too fine-grained. 40 files is too much, IMO. It is better > to group several consecutive chapters into a single file. I'm inclined to the chapter division - it seems to work well enough for GCC, and it makes it easier to rearrange chapters in the main manual, or do subsets, such as a "User's Manual", "Scripter's Manual", and the like. Stan stan@codesourcery.com ^ permalink raw reply [flat|nested] 14+ messages in thread
end of thread, other threads:[~2013-11-01 19:57 UTC | newest] Thread overview: 14+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2013-10-14 20:06 gdb.texinfo is getting too big Doug Evans 2013-10-14 20:10 ` Eli Zaretskii 2013-10-14 20:26 ` Doug Evans 2013-10-15 2:44 ` Eli Zaretskii 2013-10-16 18:55 ` Doug Evans 2013-10-16 19:01 ` Eli Zaretskii 2013-10-16 19:52 ` Pedro Alves 2013-10-16 20:06 ` Eli Zaretskii 2013-10-16 20:10 ` Paul_Koning 2013-10-16 21:41 ` Pedro Alves 2013-11-01 19:37 ` Doug Evans 2013-11-01 19:57 ` Eli Zaretskii 2013-10-16 21:29 ` Pedro Alves 2013-10-16 20:07 ` Stan Shebs
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).