Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.javascript > #17645 > unrolled thread

Potential FAQ mechanism on GitHub

Back to article view | Back to comp.lang.javascript

Contents

  Potential FAQ mechanism on GitHub Scott Sauyet <scott.sauyet@gmail.com> - 2012-12-09 20:12 -0800
    Re: Potential FAQ mechanism on GitHub John G Harris <john@nospam.demon.co.uk> - 2012-12-10 11:26 +0000
      Re: Potential FAQ mechanism on GitHub Scott Sauyet <scott.sauyet@gmail.com> - 2012-12-10 04:29 -0800
        Re: Potential FAQ mechanism on GitHub John G Harris <john@nospam.demon.co.uk> - 2012-12-10 18:35 +0000
          Re: Potential FAQ mechanism on GitHub Scott Sauyet <scott.sauyet@gmail.com> - 2012-12-10 11:03 -0800
            Re: Potential FAQ mechanism on GitHub John G Harris <john@nospam.demon.co.uk> - 2012-12-11 11:02 +0000
              Re: Potential FAQ mechanism on GitHub Jeff North <jnorthau@yahoo.com.au> - 2012-12-12 01:27 +1100
                Re: Potential FAQ mechanism on GitHub John G Harris <john@nospam.demon.co.uk> - 2012-12-11 14:52 +0000
                Re: Potential FAQ mechanism on GitHub Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2012-12-11 22:31 +0100
                  Re: Potential FAQ mechanism on GitHub John G Harris <john@nospam.demon.co.uk> - 2012-12-12 15:41 +0000
                    Re: Potential FAQ mechanism on GitHub "Jukka K. Korpela" <jkorpela@cs.tut.fi> - 2012-12-12 18:47 +0200
                      Re: Potential FAQ mechanism on GitHub Tim Streater <timstreater@greenbee.net> - 2012-12-12 23:20 +0000
              Re: Potential FAQ mechanism on GitHub Scott Sauyet <scott.sauyet@gmail.com> - 2012-12-11 06:30 -0800
        Re: Potential FAQ mechanism on GitHub Dr J R Stockton <reply1250@merlyn.demon.co.uk.invalid> - 2012-12-12 21:13 +0000
    Re: Potential FAQ mechanism on GitHub Dr J R Stockton <reply1250@merlyn.demon.co.uk.invalid> - 2012-12-12 21:27 +0000
      Re: Potential FAQ mechanism on GitHub Scott Sauyet <scott.sauyet@gmail.com> - 2012-12-13 08:29 -0800

#17645 — Potential FAQ mechanism on GitHub

I have posted a new GitHub repository containing the start of a
proposed mechanism for maintaining the comp.lang.javascript FAQ.  I'm
looking for feedback about whether this is a good idea or not, as well
as about the details of the implementation.

There's been a long thread running recently, "Maintainer of the FAQ",
with discussions ranging over topics from finding an appropriate
maintainer of the FAQ to whether a FAQ is needed, to techniques for
managing the FAQ, to details of what should and shouldn't be included
in our FAQ.  If you've been following that thread, you may find some
of the information below to be familiar.  I have made a suggestion
several times about group maintenance of the FAQ and about tools we
could use to make the job easier, including suggestions of a wiki and
for GitHub.

I finally took the time to try one of these ideas.

I reused some old code I had around to convert folders of Markdown
files to HTML files, and manually converted the fourteen sections of
Chapter 10 of the FAQ to Markdown.  These files are, I believe, in a
format appropriate to be posted to the group by a new auto-poster.  We
would just need to append the boilerplate about the location of the
entire FAQ.

The HTML output clearly demonstrates the limits of my design skills.
Someone with a better eye for design could certainly create nicer
looking pages.

The code that performs this operation right now depends on Mozilla's
Rhino, which means you need to have Java installed in order to run
it.  I would like to replace it with some simpler Node.js code, but
that's probably not a top priority.  But note that everything in the
repository now is really meant as scaffolding, something only slightly
more than a proof of concept.

I will try to update the README tomorrow with build instructions.  But
the Windows batch file in the root might make it clear enough what
needs to be done.  The main confusing issue right now is that the
folders being supplied to the script on the command line have to be
passed by full path, not simply a relative path.  I'll straighten that
out eventually.

The repository is at

    <https://github.com/comp-lang-javascript/faq-alpha>

You can see samples of the output generated from any of the links on
this page:

    <http://scott.sauyet.com/Javascript/Demo/2012-12-09b/>

The markup used to generate the pages is alongside the pages;  just
tack on "index.md" to the URL, for example:

    <http://scott.sauyet.com/Javascript/Demo/2012-12-09b/10.2/>
    <http://scott.sauyet.com/Javascript/Demo/2012-12-09b/10.2/
index.md>

The GitHub account is an Organization account, which means that I can
add additional people to it.  If we decide to go this route, I'm
hoping that there would be a group of 5 - 10 people willing to help
maintain the FAQ.

I would love to hear what you think about these ideas, and about this
implementation of them.  Are there others out there who would be
willing to help convert other sections of the FAQ?  Anyone want to
help rewrite in Node?  Anyone want to take a stab at an auto-poster,
presumably in Node?  Anyone with design skills want to take a crack at
some nicer CSS? (The HTML is mostly fixed by the Markdown parser.)  I
believe that list is probably in rough order of priority, but any help
would be gladly accepted.

Or do you think this is a waste of time?  Should I not be pursuing
this idea at all?  If so, please let me know why.

Thanks,

  -- Scott

[toc] | [next] | [standalone]

#17651

On Sun, 9 Dec 2012 at 20:12:41, in comp.lang.javascript, Scott Sauyet
wrote:

  <snip>
>You can see samples of the output generated from any of the links on
>this page:
>
>    <http://scott.sauyet.com/Javascript/Demo/2012-12-09b/>
  <snip>

Here is your first batch of comments.

1 Sans Serif is usually better for headings.

2 Code is best shown always on a separate line, and indented.

3 General principle : the style should aim to make the FAQ easy to read.
It's pretty good already.

  John
-- 
John Harris

[toc] | [prev] | [next] | [standalone]

#17652

John G Harris wrote:
> Scott Sauyet wrote:

>   <snip>>You can see samples of the output generated from any of the links on
>> this page:
>
>>    <http://scott.sauyet.com/Javascript/Demo/2012-12-09b/>

> Here is your first batch of comments.
>
> 1 Sans Serif is usually better for headings.
>
> 2 Code is best shown always on a separate line, and indented.
>
> 3 General principle : the style should aim to make the FAQ easy to read.
> It's pretty good already.

Thank you.  If the group decides to go with this general approach,
would you be willing to help with the CSS?  As I said, my own design
skills are fairly poor.

  -- Scott

[toc] | [prev] | [next] | [standalone]

#17659

On Mon, 10 Dec 2012 at 04:29:41, in comp.lang.javascript, Scott Sauyet
wrote:
>John G Harris wrote:
>> Scott Sauyet wrote:
>
>>   <snip>>You can see samples of the output generated from any of the links on
>>> this page:
>>
>>>    <http://scott.sauyet.com/Javascript/Demo/2012-12-09b/>
>
>> Here is your first batch of comments.
>>
>> 1 Sans Serif is usually better for headings.
>>
>> 2 Code is best shown always on a separate line, and indented.
>>
>> 3 General principle : the style should aim to make the FAQ easy to read.
>> It's pretty good already.
>
>Thank you.  If the group decides to go with this general approach,
>would you be willing to help with the CSS?  As I said, my own design
>skills are fairly poor.

Is this a suitable way to show drafts for comment ?

  <http://www.jghnorth.org.uk/faqdesign/faq1.html>

It's not serious yet; some changes are outstanding.

  John
-- 
John Harris

[toc] | [prev] | [next] | [standalone]

#17660

John G Harris wrote:
> Scott Sauyet wrote:
>> John G Harris wrote:
>
>>> 3 General principle : the style should aim to make the FAQ easy to read.
>>> It's pretty good already.
>
>> Thank you.  If the group decides to go with this general approach,
>> would you be willing to help with the CSS?  As I said, my own design
>> skills are fairly poor.
>
> Is this a suitable way to show drafts for comment ?
>
>   <http://www.jghnorth.org.uk/faqdesign/faq1.html>
>
> It's not serious yet; some changes are outstanding.

I believe so.  At a quick glance, it looks to me as though you wrapped
up the main body of the output generated through the process I
described in some additional markup.  The infrastructure would support
that in a fairly simple manner.  If you were looking instead to
*modify* the generated markup to support your design, it would be
significantly harder to accommodate.

  -- Scott

[toc] | [prev] | [next] | [standalone]

#17672

On Mon, 10 Dec 2012 at 11:03:57, in comp.lang.javascript, Scott Sauyet 
wrote:
>John G Harris wrote:

   <snip>
>> Is this a suitable way to show drafts for comment ?
>>
>>   <http://www.jghnorth.org.uk/faqdesign/faq1.html>
>>
>> It's not serious yet; some changes are outstanding.
>
>I believe so.  At a quick glance, it looks to me as though you wrapped
>up the main body of the output generated through the process I
>described in some additional markup.  The infrastructure would support
>that in a fairly simple manner.  If you were looking instead to
>*modify* the generated markup to support your design, it would be
>significantly harder to accommodate.

Perhaps I should have made it clearer. It's a draft css file that's 
being demonstrated. The html file is there just to show the effect of 
the draft styles. Part of it comes from the FAQ, possibly amended; part 
is demo environment.

I've updated the css file, see the link above. I've also amended one 
part of the FAQ text by replacing
   <code> ... </code>
with
   <pre><code> ... </code></pre>
This puts code on a separate line and also avoids problems with browsers 
that haven't implemented code elements yet. Would this change be much of 
a problem?

   John
-- 
John Harris

[toc] | [prev] | [next] | [standalone]

#17674

On Tue, 11 Dec 2012 11:02:59 +0000, in comp.lang.javascript John G
Harris <john@nospam.demon.co.uk>
<uYnIguEjLxxQFwH9@J.A830F0FF37FB96852AD08924D9443D28E23ED5CD> wrote:

>| On Mon, 10 Dec 2012 at 11:03:57, in comp.lang.javascript, Scott Sauyet 
>| wrote:
>| >John G Harris wrote:
>| 
>|    <snip>
>| >> Is this a suitable way to show drafts for comment ?
>| >>
>| >>   <http://www.jghnorth.org.uk/faqdesign/faq1.html>
>| >>
>| >> It's not serious yet; some changes are outstanding.
>| >
>| >I believe so.  At a quick glance, it looks to me as though you wrapped
>| >up the main body of the output generated through the process I
>| >described in some additional markup.  The infrastructure would support
>| >that in a fairly simple manner.  If you were looking instead to
>| >*modify* the generated markup to support your design, it would be
>| >significantly harder to accommodate.
>| 
>| Perhaps I should have made it clearer. It's a draft css file that's 
>| being demonstrated. The html file is there just to show the effect of 
>| the draft styles. Part of it comes from the FAQ, possibly amended; part 
>| is demo environment.
>| 
>| I've updated the css file, see the link above. I've also amended one 
>| part of the FAQ text by replacing
>|    <code> ... </code>
>| with
>|    <pre><code> ... </code></pre>
>| This puts code on a separate line and also avoids problems with browsers 
>| that haven't implemented code elements yet. Would this change be much of 
>| a problem?
>| 
>|    John

Huh???? The HTML code element has been around since HTML 1.0.
The code element is an inline element much like em, b, u etc.
The pre element is a block element which must enforce the whitespace
used within it and forces a new line at the beginning and end of the
block.

[toc] | [prev] | [next] | [standalone]

#17676

On Wed, 12 Dec 2012 at 01:27:38, in comp.lang.javascript, Jeff North
wrote:

  <snip>
>Huh???? The HTML code element has been around since HTML 1.0.
>The code element is an inline element much like em, b, u etc.
>The pre element is a block element which must enforce the whitespace
>used within it and forces a new line at the beginning and end of the
>block.

Yes indeed. I searched the HTML 4.01 standard for 'element code', but
it's parcelled up with others :
<!ENTITY % phrase "EM | STRONG | DFN | CODE |
                   SAMP | KBD | VAR | CITE | ABBR | ACRONYM" >
so I missed it, but I did see the example in 7.5.2 of code being
displayed in a pre element :-(

  John
-- 
John Harris

[toc] | [prev] | [next] | [standalone]

#17679

Jeff North wrote:

> On Tue, 11 Dec 2012 11:02:59 +0000, in comp.lang.javascript John G
> Harris <john@nospam.demon.co.uk>
> <uYnIguEjLxxQFwH9@J.A830F0FF37FB96852AD08924D9443D28E23ED5CD> wrote:

It is supposed to be an attribution _line_, not an attribution novel.
 
>> I've updated the css file, see the link above. I've also amended one
>> part of the FAQ text by replacing
>>    <code> ... </code>
>> with
>>    <pre><code> ... </code></pre>
>> This puts code on a separate line and also avoids problems with browsers
>> that haven't implemented code elements yet. Would this change be much of
>> a problem?
>> 
>>    John
> 
> Huh????

Your Question Mark key is malfunctioning.  And “|” is supposed to indicate 
third-party quotes only.

> The HTML code element has been around since HTML 1.0.

No, there was never an HTML 1.0.

> The code element is an inline element much like em, b, u etc.

Yes, although it is spelled “CODE element” before HTML5 (WD).

> The pre element is a block element which must enforce the whitespace
> used within it

Yes, unless overridden by stylesheets, particularly the “white-space” CSS 
property.

> and forces a new line at the beginning and end of the block.

No, that is what some default stylesheets do.


PointedEars
-- 
Prototype.js was written by people who don't know javascript for people
who don't know javascript. People who don't know javascript are not
the best source of advice on designing systems that use javascript.
  -- Richard Cornford, cljs, <f806at$ail$1$8300dec7@news.demon.co.uk>

[toc] | [prev] | [next] | [standalone]

#17681

On Tue, 11 Dec 2012 at 22:31:25, in comp.lang.javascript, Thomas
'PointedEars' Lahn wrote:
>Jeff North wrote:

  <snip>
>> The code element is an inline element much like em, b, u etc.
>
>Yes, although it is spelled “CODE element” before HTML5 (WD).
  <snip>

Well, the HTML standards had to spell it some way. As tags are case
independent, <cOdE> is legal and so is <code>.

It was XHTML that insisted on tag names being lower case.

And "before HTML5" is a bit premature, to say the least.

  John
-- 
John Harris

[toc] | [prev] | [next] | [standalone]

#17682

2012-12-12 17:41, John G Harris wrote:

> On Tue, 11 Dec 2012 at 22:31:25, in comp.lang.javascript, Thomas
> 'PointedEars' Lahn wrote:
>> Jeff North wrote:
>
>    <snip>
>>> The code element is an inline element much like em, b, u etc.
>>
>> Yes, although it is spelled “CODE element” before HTML5 (WD).
>    <snip>
>
> Well, the HTML standards had to spell it some way. As tags are case
> independent, <cOdE> is legal and so is <code>.

Of course. Even many novices know that, and this makes the off-topic 
lectures of “Thomas 'PointedEars' Lahn” even more ridiculous. (He also 
lectures on Usenet conduct, including “From” lines, still failing to 
obey the good old rule that the “From” line contains the full name and 
e-mail address of the sender and nothing more.)

> It was XHTML that insisted on tag names being lower case.

Or insists; XHTML isn’t actually dead.

> And "before HTML5" is a bit premature, to say the least.

In reality, “HTML5” is just as case-insensitive as HTML specs have used 
to be. “HTML5” lets you use XML syntax, too, but “HTML5” as such does 
not require tag names in any particular case. In fact, the “HTML5” 
drafts, and the “Living HTML Standard” documents, intentionally (but 
rather confusingly) use case variation in tag names.

The only excuse for posting these off-topic notes are that they help to 
reveal some of the bogosity of the person that has volunteered to become 
the comp.lang.javascript FAQ maintainer, despite his continued rants 
“there is no javascript”.

-- 
Yucca, http://www.cs.tut.fi/~jkorpela/

[toc] | [prev] | [next] | [standalone]

#17683

In article <kaacf6$4uh$1@dont-email.me>,
 "Jukka K. Korpela" <jkorpela@cs.tut.fi> wrote:

> 2012-12-12 17:41, John G Harris wrote:
> 
> > On Tue, 11 Dec 2012 at 22:31:25, in comp.lang.javascript, Thomas
> > 'PointedEars' Lahn wrote:
> >> Jeff North wrote:
> >
> >    <snip>
> >>> The code element is an inline element much like em, b, u etc.
> >>
> >> Yes, although it is spelled “CODE element” before HTML5 (WD).
> >    <snip>
> >
> > Well, the HTML standards had to spell it some way. As tags are case
> > independent, <cOdE> is legal and so is <code>.
> 
> Of course. Even many novices know that, and this makes the off-topic 
> lectures of “Thomas 'PointedEars' Lahn” even more ridiculous. (He also 
> lectures on Usenet conduct, including “From” lines, still failing to 
> obey the good old rule that the “From” line contains the full name and 
> e-mail address of the sender and nothing more.)
> 
> > It was XHTML that insisted on tag names being lower case.
> 
> Or insists; XHTML isn’t actually dead.
> 
> > And "before HTML5" is a bit premature, to say the least.
> 
> In reality, “HTML5” is just as case-insensitive as HTML specs have used 
> to be. “HTML5” lets you use XML syntax, too, but “HTML5” as such does 
> not require tag names in any particular case. In fact, the “HTML5” 
> drafts, and the “Living HTML Standard” documents, intentionally (but 
> rather confusingly) use case variation in tag names.
> 
> The only excuse for posting these off-topic notes are that they help to 
> reveal some of the bogosity of the person that has volunteered to become 
> the comp.lang.javascript FAQ maintainer, despite his continued rants 
> “there is no javascript”.

+1

-- 
Tim

"That excessive bail ought not to be required, nor excessive fines imposed,
nor cruel and unusual punishments inflicted"  --  Bill of Rights 1689

[toc] | [prev] | [next] | [standalone]

#17675

John G Harris wrote:
> Scott Sauyet wrote:
>> John G Harris wrote:

>>> Is this a suitable way to show drafts for comment ?
>>>     <http://www.jghnorth.org.uk/faqdesign/faq1.html>
>>> It's not serious yet; some changes are outstanding.
>
>> I believe so.  At a quick glance, it looks to me as though you wrapped
>> up the main body of the output generated through the process I
>> described in some additional markup.  The infrastructure would support
>> that in a fairly simple manner.  If you were looking instead to
>> *modify* the generated markup to support your design, it would be
>> significantly harder to accommodate.
>
> Perhaps I should have made it clearer. It's a draft css file that's
> being demonstrated. The html file is there just to show the effect of
> the draft styles. Part of it comes from the FAQ, possibly amended; part
> is demo environment.

I'm sorry, I did understand that.

The main thing I'm trying to work on is the infrastructure for
maintaining the FAQ.  Although in the end the styling is very
important, I'm not at all focused on it yet.  So from my perspective,
if what you're doing could be easily handled by the process I'm
proposing, then it's simple to say yes.  If not, then I have to
consider it carefully.  So if you're using the HTML as generated by
the Markdown -> HTML process I'm proposing, with whatever wrappers,
including CSS, then I'm not at all concerned.

> I've updated the css file, see the link above.

I certainly noticed that.  I have no comment so far.  I'm not sure
whether I prefer the one I presented, the one you presented, or the
current one.  But I'm more than willing to wait on that and defer to
whatever consensus arises.


>  I've also amended one
> part of the FAQ text by replacing
>    <code> ... </code>
> with
>    <pre><code> ... </code></pre>
> This puts code on a separate line and also avoids problems with browsers
> that haven't implemented code elements yet. Would this change be much of
> a problem?

This is where things change a bit.  This becomes an issue of the
source format.  I would not want to change the Markdown parser to
change all bits that look like this:

    A line with `some code` embedded

into

    <p>A line with</p>
    <pre><code>some code</code></pre>
    </p>

But I have no problem changing the markup in the file in question from
this:


    You can't. The browser's history cannot be modified. However,
    you can use `self.location.replace(url);`  in some browsers
    to replace the current page in the history.

to this:

    You can't. The browser's history cannot be modified. However,
    you can use

        self.location.replace(url);

    in some browsers to replace the current page in the history.

which is cleaner and clearer in my opinion.  But for now, I'm trying
to stick with the original as closely as possible, and that's how it
appears in the current FAQ:

    <http://jibbering.com/faq/#disableBackButton>

I posted both examples:

    <http://scott.sauyet.com/Javascript/Demo/2012-12-09b/10.1/>
    <http://scott.sauyet.com/Javascript/Demo/2012-12-09b/10.1/
index.md>
    <http://scott.sauyet.com/Javascript/Demo/2012-12-09b/10.2/>
    <http://scott.sauyet.com/Javascript/Demo/2012-12-09b/10.2/
index.md>

Does this make sense?

  -- Scott

[toc] | [prev] | [next] | [standalone]

#17685

In comp.lang.javascript message <bfaec2aa-6745-41ce-aa39-c049e5904c80@4g
2000yqv.googlegroups.com>, Mon, 10 Dec 2012 04:29:41, Scott Sauyet
<scott.sauyet@gmail.com> posted:

>Thank you.  If the group decides to go with this general approach,
>would you be willing to help with the CSS?  As I said, my own design
>skills are fairly poor.

That would be good, if it caused you to produce a non-designed FAQ.

-- 
 (c) John Stockton, nr London, UK.  Mail via homepage.  Turnpike v6.05  MIME.
  Web  <http://www.merlyn.demon.co.uk/> - FAQqish topics, acronyms and links;
  Astro stuff via astron-1.htm, gravity0.htm ; quotings.htm, pascal.htm, etc.
 No Encoding. Quotes before replies. Snip well. Write clearly. Don't Mail News.

[toc] | [prev] | [next] | [standalone]

#17686

In comp.lang.javascript message <5e684468-d1ae-4a31-a5b7-cba01316b6cc@u1
9g2000yqj.googlegroups.com>, Sun, 9 Dec 2012 20:12:41, Scott Sauyet
<scott.sauyet@gmail.com> posted:

>
>Or do you think this is a waste of time?  Should I not be pursuing
>this idea at all?  If so, please let me know why.


It will not work as a provider of a FAQ suitable got a general purpose
Usenet JavaScript group.  A few experts with nothing better to do will
compete in adding complications.

The thing that is needed is clarity of thought in the planning of the
content of the FAQ.

For example, analyse "9.4 How do I modify the content of the current
page?".  The question is clearly not what it should have been (IIRC, I
asked it) - it should (for me) refer to the visual textual content.

The answer should be along the lines of
 (1) Decide on or create the element to be modified
 (2) Obtain a reference to the desired element of the page
 (3) Assign to the property of the element that controls its appearance
     in the desired manner.
Lines should link to appropriate new sections.

For that question as written, the modification might include hiding and
un-hiding, moving in an XY sense, repositioning in the DOM tree,
altering the CSS in a button, etc.  The answer should include everything
compatible with the chosen wording of the question.

A FAQ should rarely include the questions literally as actually asked;
but it should include questions that the questioner will recognise as
answering what he was thinking of asking.

-- 
 (c) John Stockton, nr London, UK.  For Mail, see Home Page.  Turnpike, WinXP.
 Web  <http://www.merlyn.demon.co.uk/> - FAQ-type topics, acronyms, and links.
 Command-prompt MiniTrue is useful for viewing/searching/altering files. Free,
 DOS/Win/UNIX now 2.0.6; see <URL:http://www.merlyn.demon.co.uk/pc-links.htm>.

[toc] | [prev] | [next] | [standalone]

#17693

Dr J R Stockton wrote:
> Scott Sauyet posted:

>> Or do you think this is a waste of time?  Should I not be pursuing
>> this idea at all?  If so, please let me know why.
>
> It will not work as a provider of a FAQ suitable got a general purpose
> Usenet JavaScript group.  A few experts with nothing better to do will
> compete in adding complications. [ ... ]

I think you're missing some of the point, though.  This technique does
not dictate whether there is a single FAQ Maintainer or multiple ones,
or, if there is a single one or a small group, whether or not they
have to accept suggestions made by others.  This would simply be a way
to make it easier to maintain the FAQ sections, to make proposed
changes, to accept those proposals if desired, and to auto-post the
sections.

Nothing in here would affect the actual editorial mechanisms regarding
the FAQ.  Those still needs to be figured out.

  -- Scott

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.javascript

csiph-web