Date: 08 Nov 2000 08:12:10 -0500 From: Lowell Gilbert <lowell@world.std.com> To: bokr@accessone.com (Bengt Richter), freebsd-doc@freebsd.org Subject: [from freebsd-security] Re: [FAQ] Ideas for automatic FAQ extraction? Message-ID: <rd6wveea9qt.fsf@world.std.com> In-Reply-To: bokr@accessone.com's message of "7 Nov 2000 09:17:48 %2B0100" References: <3.0.5.32.20001107002217.009641f0@mail.accessone.com>
next in thread | previous in thread | raw e-mail | index | archive | help
This is really a -doc topic, rather than a -security one, so I'm sending my message accordingly. bokr@accessone.com (Bengt Richter) writes: > I have a pretty goodsized archive from this mailing list, > with a lot of valuable Q's and A's, but it would take a > *lot* of editing to make a FAQ out of it all. So I thought > to ask: (see Q: below, after topic header ...) > > [T: Markup syntax for automatic FAQ extraction from posted text.] > [C: The above T: item defines the beginning a topic scope. > This is a comment to be included in the extracted FAQ material.] > > [Q: Has anyone defined a simple markup syntax that > would let people delimit *parts* of their posting > so that a simple script could extract material to > generate a FAQ document automatically? ] > [A: I am proposing this as a straw man, > but there are probably others. ] The idea is fine, but my opinion is that it isn't worth the effort. Entries should only be added to a FAQ if they're asked frequently, and trying to combine writing a mailing list answer with a FAQ entry is not really going to make things easier. I consistently find that I have to do a lot of rewriting when I submit FAQ entries, even when I started with a mailing list message, so I doubt this approach would get a lot of buy-in. People who are willing to do the extra work can just write the proposed FAQ entry, and send the text as a response as well as a PR. It *is* possible that we could use a "security" section of the FAQ, but I'm not sure about that, because it's hard to separate security from system administration in general, which already has a section. I submitted some text (several questions and answers worth) about passwords a year or two back, and it's still sitting in an open PR. > This is a comment that wouldn't show up in the > output FAQ. Only stuff inside [] brackets gets extracted. > > [Q: What about followup questions? ] > [A: They'd alternate, like a normal dialog, unless they > narrowed in on something. Then nesting might be > called for, like usenet threads.] > > [Q: How does topic scope end?] > [A: With start of another, or EOF. Nesting Q: and A: scopes > within a T: is permitted, but then it takes X: to > exclude text. [X: This is inside an A: scope, so it > takes the X: at the beginnig of this to exclude this.] > ] > This is not inside brackets, so > it doesn't get extracted for a FAQ. This represents > the parts of postings that you don't want in the FAQ, > so you don't bracket it. > > [Q: How much thought has gone into this?] > [A: Not whole lot, but it's pretty simple. [C: This is a comment > that is not an answer, but would get carried along, > and it has nested scope. Extracted material would be pretty-printed.] > [Q: What should this question refer to by its position?] > [A: It should have been a nested follow-on question about > the amount of thought or something in the answer, > or something like that.] > [X: Inside the outermost brackets, it takes X: bracketing > to exclude text like this. This is still inside an A: scope. ] > ] <- ends the A: above, with its nested C:, Q:, A: and X:. This > part is outside, and excluded. > > Even something as trivial ( well, the nesting/threading makes it a > little less trivial, but still ) as the above markup might have > a lot of effect. It's cheap to try. A little perl could easily make > HTML or text FAQ output. [C: Maybe there should be an optional > [K: keywords] form to support searching and indexing? BTW the C: > makes the [K: ...]'s here be included, but not 'evaluated' since > they're inside the C: (comment) scope.] That's pretty close to trivial, but it's not *really* much easier than writing docbook, and you can always submit raw text in a PR and hope a committer will do the markup for you. That kind of docbook markup is almost precisely equivalent, and can easily be done cargo-cult style. > [C: Maybe a special alternate to [T: ...] could designate a final > version arrived at by consensus, say add an exclamation point after the > colon on things, like [T:! ...] or [A:! ...], etc. or else just use > the latest date posting containing a particular [T: ...] topic. > To update a [T: Topic line] you'd follow it immediately with its > replacement, and leave the old, to tie the new into the same succession. ] > > [C: We could start with just the T:, Q:, and A: forms and no nesting, > and see how it feels. E-mail quoting syntax will complicate extraction > a little, but not that bad, I'd guess. ] > > Thoughts? > > Regards, > Bengt Richter > (MOIB - Member of Idea Brigade ;-) > > > > To Unsubscribe: send mail to majordomo@FreeBSD.org > with "unsubscribe freebsd-security" in the body of the message To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?rd6wveea9qt.fsf>