Subject:
|
Re: Format of FAQ items
|
Newsgroups:
|
lugnet.faq
|
Date:
|
Fri, 23 Apr 1999 22:13:57 GMT
|
Viewed:
|
1716 times
|
| |
|
|
In lugnet.faq, jsproat@geocities.com (Sproaticus) writes:
> I think that whatever format is used, it should allow multiple Q+A's in a
> single file, with the technical possibility of having it all in one file.
How come? For specifying the ordering? For ease of editing?
What about translations? Maintenance? Bookmarking? Grepping?
> Another possible feature would be to allow a master file to explicitly
> include a subordinate file during parsing; this would greatly facilitate
> separation of other FAQs, such as the LDraw FAQ.
Something analogous to #include in C then? Would that slurp in an entire
sub-FAQ? Or only relevant starter-questions? At the root level, someone
probably only wants to read "What is this LDraw thing?" and be able to click
deeper to see all the rest of the stuff, but probably not see all 35 FAQ
questions at the top level...?
> Once I figure out what format to use, I'll post a broilerplate for people to
> submit Q+A's (or just Q's) for the FAQ.
>
> Potential format examples follow. (1)
>
> -----------------------------------------------------------------------------
> email headers style
> plus: more easily by humans
(and easier for machine too)
> minus: a separate file for each question?
I see this as a big plus.
> - if so, how to sort, how to name?
Sort hierarchically on category (i.e. newsgroup tree), and within that sort
lexicographically on category name (i.e. by newsgroup name within family of
newsgroups), and within that sort numerically by filename. Couldn't be
simpler than that. The only thing gunky about this is inserting a new Q&A
pair betwixt two pre-existing earlier items. (But it's not -that- gunky.)
A logical alternative to numeric-based filenames would be name-based
filenames with an index file giving a list of filenames in order. An index
file for each category is probably useful anyway to specify blanket-defaults
for individual questions (to avoid repetition within them) and an index file
would make a great category intro-page (as a web page).
> [...]
> -----------------------------------------------------------------------------
> xml style
> plus: tons of entries in same file,
I see that as a minus!
(See above and http://www.lugnet.com/news/display.cgi?lugnet.faq:64 )
> implied sort order can be enforced
This is certainly good
> minus: not as easily read by humans
or computers (i.e., simple text-processing tools)
> minus: XML and / or HTML token chars in entry text may need to be escaped
> -----------------------------------------------------------------------------
>
> <ENTRY>
> <ENTRYHEADER>
> <CATEGORY>Auction & Shipping</CATEGORY>
> <SUBCATEGORY>Awareness</SUBCATEGORY>
> <SUBJECT>You mean I can get money for my old LEGO®?</SUBJECT>
> <CONTENT-LANGUAGE>en</CONTENT-LANGUAGE>
> <NEWSGROUPS>lugnet.market.*</NEWSGROUPS>
Wouldn't the XML way to do the newsgroups be--?
<NEWSGROUP>ng1</>
<NEWSGROUP>ng2</>
<NEWSGROUP>ng3</>
:)
> <AUTHOR>Todd Lehman</AUTHOR>
> <FAQ-DATE>19990423</FAQ-DATE>
Since there can be multiple authors (due to revisions or collaboration)
there would need to be multiple dates -- one for each revision. This could
get pretty unnecessarily complex in XML, but is easy in plaintext:
Author: Todd Lehman, 3 Jan 1996
Author: Todd Lehman, 17 Mar 1996
Author: Jeremy Sproat, 23 Apr 1999
> </ENTRYHEADER>
> <ENTRYTEXT>
> Yes, absolutely -- anything that says LEGO® on it.
>
> [quote snipped]
>
> Sell your old LEGO® and you will be rewarded. But don't sell it to
> the first
> bloke who offers you $10 for it -- seek out the people who seek what you
> have, and both of you are winners.
> </ENTRYTEXT>
> </ENTRY>
>
> -----------------------------------------------------------------------------
>
> Any feedback on what kind of format you'd prefer on your end would be
> great. I have plenty of time this weekend to get cracking. :-,
I think XML is beautiful -- and I love it -- but I think it's way overkill
for this application.
A format/structure that's easily processable by many different types of text
tools (awk, perl, sed, grep, wc, diff, etc.) -- and even a webserver -- is
really a big, big plus over XML right now. Down the road, if only a small
subset of HTML were used in the bodies of the answers, it would be pretty
darn straightforward to machine-convert everything into XML. But it's not
straightforward yet these days to work directly with XML. Maybe in 18
months...
--Todd
|
|
Message has 2 Replies:
 | | Re: Format of FAQ items
|
| (...) You've convinced me otherwise now. Mea culpa. :-, (...) I think it would take in the whole sub-FAQ. This is (currently) my strategy for giving localized names to the different categories. Someone looking for starter questions could probably (...) (26 years ago, 23-Apr-99, to lugnet.faq)
| | | Re: Format of FAQ items
|
| (...) Let me expand on this. It all depends on how it's converted into readable form. A one-file FAQ would certainly slurp everything in. An HTML conversion might take just the question titles to put up on the first page. Or maybe just the section's (...) (26 years ago, 23-Apr-99, to lugnet.faq)
|
Message is in Reply To:
| | Format of FAQ items
|
| Todd, I'm geared to start snarfing the RTL Auction & Shipping FAQ, to start giving form to the LUGNET FAQ. (LUGFAQ? :-) I am torn between two data formats, though it should be relatively easy to switch from one to the other. I think that whatever (...) (26 years ago, 23-Apr-99, to lugnet.faq)
|
82 Messages in This Thread:
  
 
- Entire Thread on One Page:
- Nested:
All | Brief | Compact | Dots
Linear:
All | Brief | Compact
This Message and its Replies on One Page:
- Nested:
All | Brief | Compact | Dots
Linear:
All | Brief | Compact
|
|
|
|
