[lgfaq] Editing this is now officially like pulling teeth

[zakk]

On Mon, 2002-10-07 at 12:46, Chunky Kibbles wrote:
> OK. I'm right here, right now, proposing some new standards for the
> lgfaq, because editing it is becoming a chore, and the whole thing is
> becoming harder and harder to read, aswell.
>
> Formatting the text in the editor:
> All lines should be 70 or 72 cols. Just push everything through "fmt -s"
> when you're done, and it'll be fine. If you need a tutorial for vi on
> this, I will gladly provide one. [it'll be a two-line item]
>

I have word wrapping on in gvim. Don't mind word wrapping in general for
the lgfaq, however, I also think this will /break/ some <PRE>'d items.
Don't do this blindly with a tool thinking everything will look right.
 
>
> And although HTML tags as ALL CAPS are officially deprecated, I like
> them, I think they make the source easier to read.
> 
This is true, anyone who doesn't put their tags in CAPS will be handed
over to the Ninja Hack Squad for reducation.
>
> Question and answer formats:
> It is the browser's job to get the final output formatting right. We
> even say that in the coding_guidelines.
>
> Notably, for almost everything we do, we should NOT need to use <BR>
> at all, ever. The raw HTML for any given section should appear thusly:
>
>
> <UL>
> 
> <LI>
> <P CLASS="Question">Q: How do I do {mumble}?</P>
> <P CLASS="Answer">A: You could try this: {mumble}</P>
> <P CLASS="Answer">A: Alternatively, try this: {different mumble}</P>
> </LI>
> 
> ....
> 
> </UL>
> 
> I'm reserving judgement one some of this, but the "Q:" and "A:" need
> to be there for browser that don't support stylesheets.
> 
> We will then have a stylesheet common to all of this.
>
I don't believe style sheets will work everywhere. With treke's XML
parser it should be easy to test this.
> 
> Sections:
> Sections should be made available piecemeal. As in, it should be
> possible to view "/lgfaq/index.php?section=install" and just see that.
> The rest of the time, I'm not sure, but I think a <HR> would be really
> good for sepatating the sections. Pure eye-candy, open to debate.
> 
> 
> 
> Most importantly, it's time we had a search feature. I think that
> anytime now would be a good time to actually do some work on greg's
> XML parser, hence rendering most of what I've said invalid, as it will
> be easy to change whenever.
>
You're right about the search.
>
> I don't mind spending a few minutes converting what we have now to
> XML. I believe it will be worth it in the long run. But I definitely
> won't do it until at least the 70-col standard is agreed upon.
> 
> Gary (-;
> 
> PS Think what you will, but this was sparked off because I've just
> read the UT2k3 installation help for the first time, and it's a
> hassle. Agree ot disagree, but just bloody look at it. It's actually a
> challenge to read.
I think you're right in general that it can be challenging to read.
But I also think that people would likely skip over large portions if it
wasn't pushed in front of them. Largely, the LGFAQ is bloody huge, and
perhaps the most popular item on icculus.org ever, so, I think it's
important to make sure we can backtrack if anything we do is extremely
stupid. CVS is nice for this, but I don't know how we could reverse
things on a large scale with it.

Someone really /should/ push everything to treke's xml parser. 
-- 
-zakk
zakk at timedoctor.org
http://www.icculus.org/lgfaq/