Edevdocs are a problem.

Firstly, I've seen a lot of edevdocs around that seem to indicate that people aren't aware of the difference between edevdoc's and superdocs. So, you know, maybe we need a bit of documentation. Hey, it's just a thought.

Secondly... brackets. Brackets are, of course, a pain on Everythings in general, what with parselinks being used somewhat universally on content.

There is no simple, elegant way to denote a bracket that will survive a trip through parselinks. The standard way of passing a bracket through parselinks doesn't pass a bracket through at all; it just passes the HTML entity for a bracket, [. This only happens to look a bit like a bracket when your browser renders HTML. As far as, say, JavaScript is concerned, though, it's not a bracket at all.

The 'solution' we currently have in place to this problem, is, in a word, wrong. The solution is that while normal documents are displayed with parselinks, edevdocs are displayed with devparselinks, an entirely different function.

This brings trouble when we have a javascript utility, such as E2 Bookmarklets or Writeup table formatting utility which we want to open up to the general E2 user population rather than just edev, the only real way to do this is to convert the edevdoc (viewable only by edev members) into a document, viewable by all. And here we can get bitten by the difference between documents and edevdocs.

E2 Bookmarklets uses its own scheme to get round the lack of brackets; if it had used the edevdoc scheme, it would be useless in a document.

There are ways to get round the lack of brackets, of course.

  • construct any regular expressions using ASCII equivalents, and for array dereferencing, parselinks can be defeated by using, eg:
    array /*[*/ [i /*]*/ ] = f(i);

    This causes the HTML generated by parselinks to be encapsulated inside the javascript comment, while the following [ is thought to be inside the '[]' so isn't interpolated, and the closing ']' is thought to be an unmatched ']' so isn't interpolated.

    Please note, the technical term for this method is 'A Gross Hack', and if I find anyone attempting it, I shall kill them. Or... you know, laugh at them. Whichever I feel like at the time.

  • encode the code (eg. with escape) and store in in a string, which can then be unescaped and evaluated. The edev JavaScript escaper will do this for you.

However, I would like to propose that we actually solve this problem, rather than simply bubble-pushing it. I see two solutions:

  1. Create a publically accessible nodetype that uses devparselinks for its display page, which edevdocs can be transformed into to make them publically accessible. Naturally, for the same reasons that edevdocs can only be viewed by edev members, we would want to ensure that the new nodetype can't be created by non-deity edev members, but can easily be created from an edev member's edevdoc. Alternatively,..
  2. Beef up parselinks so that it doesn't catch brackets which are inside HTML tags or HTML comments (a little tricky perhaps), so it ignores brackets inside properly commented-out scripts. Such a parseLinks might look a little like this:

        my ($field) = @_;
        my ($text) = $$NODE{$field};
        join "-->", map {
            my @a = split /<!--/, $_;
            $a[0] =~ s/\[(.*?)\]/linkNodeTitle ($1, $NODE)/egs;
            join '<!--', @a;
        } split /-->/, $text;

    Not quite as elegant as the current definition, but certainly does the job.