• The archive vars should have their own category, as well as the categories they're in now. They're all over the damn place, and hard to find.
• There are several run_hook commands that are not listed in the Hooks Admin Tool. I think all the available hooks should be listed.

--
Discuss the art and craft of writing

• queue_edit_max_time should be in the Stories category, not General. I had to search for it because I couldn't remember what it was called.
• spam_votes_percentage and spam_votes_threshold should be in the Stories category. I ran across them in the Comments category for some reason.
• max_comments_submit should only be in the Comments category if rate_limit_minutes is, as well. It doesn't really make sense on its own.
• block categories should probably be reorganized to more closely match var categories. I know, I did the initial setup, so blame me for the strange organization there.
• use_ads says "DO NOT ENABLE ADS!!" and refers the user to a nonexistant section of the current SAG. Are ads safe to enable yet? If so, the description of this var should definitely be changed.
• if you turn ads on, "your advertisements" appears in the user box, but "new ad" doesn't.
• In the Ad admin tool, "Ad Listing" displays example ads, too. This may have been intentional, but it just seemed funny to me.
• Some strange stuff with dynamic comment mode. I seem to have gotten it working on a brand new install though, after panner fixed the scoop.sql file. No word yet on an older install with the dynamic patches, though.
• why does the var that, by its description, should be use_topic_icons is use_topics? How do you shut off icons but not topics, vs shutting off topics entirely?

I may also need help describing the ad server, payment processing, subscription, file upload, and subsection administration. I will play with them and see what I can do on my own, but I will definitely need somebody to read those sections over and tell me if I've gotten anything wrong.

Anyhow, I've been working on this all day, so I think I need a break. The version linked to in the story is updated to what I have as of now: 14,000+ words. Go ahead, read it all. I dare you :-)

--
Discuss the art and craft of writing

I found some vars in the code that aren't in the database. I've just made a patch to add them, with descriptions and sensible defaults (namely, whatever the code uses if the var doesn't exist).

There are some interesting vars hidden away in the code. Like hide_story_navbar, which gets rid of that rather useless next/previous story navbar at the bottom of stories. I've never been able to tell what it considers "next" and "previous" stories...

Anyhow, can somebody explain to me what the "old" scoring and the "new" scoring are that the (hidden) var use_new_scoring switches between?

Also, there's a "hidden" pref as well, that allows the user to set the time before his cookie expires. Since the pref isn't settable, and the var is hidden, the cookie always uses the default of 30 days.

What exactly does hide_disabled_comments do? As near as I can tell, it excludes comment search results from stories whose commentstatus is -1, ie, comments disabled. Can you disable comments to a story after a whole bunch have been posted or something?

real_initial_rating appears to be used only if a variable is 1, and it's hardcoded to 0 only a few lines above. Was this supposed to eventually be something useful?

--
Discuss the art and craft of writing

As in my previous comment, I found some missing blocks, and am working on an sql patch to add them. They're a bit trickier, since the code doesn't really tell me what the content should be the way it did with the missing vars.

Anyhow, some interesting things I found while reading the code to puzzle out what the missing blocks were for:

• A whole bunch of the less-used stuff is quite specific to k5. Not really a surprise, but probably should be generalized.
• some subscription-related perms are missing, like, oh, 'allow_subscription'. The one I noticed first was 'sub_allow_group_change', which allows Scoop to automatically change a user's group when he subscribes. Since it's missing, the admin(s) always gets an email telling them to change the group manually.
• the dynamic comment stuff uses the rootdir in a non-Scoop-standard way. It works because it uses old-style URLs, but it should probably be fixed anyway. Basically, if the rootdir var is empty, it substitutes "/" and uses that instead, so you could get either /rootdir or / as values. With the old-style URLs, that means either /rootdir?op= or /?op=, both of which work.
• do ads ever have a lot of HTML in the code.
• hey look! there *is* something there to mark subscribers on their comments! A block called mark_<group>, and it's placed in the comment with |member|
• |new_story_flag| maybe should've been handled like |new| and the block new_comment_marker; the former is in the comment block, the latter is the value that's inserted if relevant, but with new_story_flag it's both in the story_summary block and the name of the block with the value, and there's some code there to apply it if relevant.
• author_edit_instructions is interpolated into author_edit_console, but the console already contains instructions. Perhaps not needed?
• A consistency suggestion: in index_template, the title bar is there and the content is filled in by a box; in all the other templates, the title bar must be created by the code as part of |CONTENT|. Can we pick one or the other? Perhaps like the index_template, and handle it the way boxes handle their titles and bodies?
• When making the "pay with" links in the payment stage of advertising, Scoop uses https://(cookie_host) and not the secure_site_url set in site controls

--
Discuss the art and craft of writing

Just poking around ads to see what I could learn. It appears that only text ads work, and banner ads simply won't, because the special block IMAGE_PATH isn't interpolated by the code, so the image won't be shown - or even asked for.

It also appears that if you change the ad template block and add a recognized special block to it, the ad code doesn't add it to the required fields it gives you to fill in. (I copied the basic_banner_ad_template - missing in scoop.sql but present in the patches - and it had no link, which I noticed after activating it in the advertising system. I added the link in the block, but the ad admin system won't give me the link text box.)

Also, the table subscription_info was created in 0.8-0.9/patch-41-Subscriptions.sql but is missing entirely from scoop.sql.

Actually, the entire patch-41 is missing from scoop.sql - I don't have the Subscriptions Admin Tool on my dev site at all. However, some of the missing blocks I put in my sql patch are there. I'm betting most of the other missing blocks are in sql patches that weren't applied to scoop.sql...

And how do you give only subscribers access to certain boxes? Stuff like diary subscriptions and comment replies are done through boxes, but I can't find a way of selectively allowing them.

Final question: why the hell am I doing this on a Saturday night?

--
Discuss the art and craft of writing

Yes, they're almost done. Here is the information I don't know:

• What else (apart from what's already in section 3) confuses admins new to Scoop? (this info is for 3.2 Where Do I Start?)
• How do you anonymize an account? Does that feature exist, or is it a k5 hack?
• When was the dynamic comment stuff added? Sites newer than that seem to "just work" (at least, my dev site did, and it had a clean db) but sites older than that need some block tweaking.
• can somebody help me describe subsections, their use and administration? I've never used them, and for some reason I'm just stuck on the thought that they're confusing.
• does the variable use_topics turn topics off entirely as the name suggests, or just topic images, as the code suggests?
• Do you have any general tips that aren't covered in other parts of section 3? (Currently, the only one I have is a reminder that boxes can run any program on the server, so be careful how you give out permissions.)
• Can somebody describe to me what Scoop's payment processing is capable of? (This is for section 4, features)
• does install.pl use the root (or permission to create databases) user as the user in the apache config files? If so, that's not good. I'd rather that be fixed than document it in that state.
• what is the command to upgrade from a numbered release to the latest CVS version?
• Stuff like clustering, install on multiple servers, behind a proxy, log analysis with multiple Scoop servers, large site tips. This is for section 2.8 Scoop for Large Sites.

I don't have a secure server available, though I could probably set one up if I really wanted - but until and unless I do, I can't muck about and figure out how to set up payment processing. That section will be blank until I figure things out.

I believe I will start section 5 now. :-)

--
Discuss the art and craft of writing

• The new story admin tool clears the title, intro copy, and extended copy if you forget to set a topic and section, then complains that you don't have a title or intro copy.
• sections and topics have similar-but-different UI: list to the right, details to the left is the same; push a distinct delete button or select a delete checkbox then save as usual is different. Since boxes, blocks, and vars all use the second method, it may be worth changing topics to use it as well.
• do section permissions override normal permissions, or vice-versa? (ie, the section "post comments" permission vs. the general comment_post permission)
• the perm edit_perms doesn't appear to be used in the code, according to grep. edit_groups is used to determine if a user can edit the groups and their permissions.
• the perm show_perms also doesn't appear to be used anywhere. The only place it shows up is in the perm list, according to grep
• I'm not sure exactly what the perm show_hidden_sections does - rather, under what circumstances it is useful and used.

--
Discuss the art and craft of writing

I think a special case needs to be added to the box to catch the parameter "all"...

--
Discuss the art and craft of writing

Have a box appear when there's new ads/RDFs/stuff that the admin needs to handle. It would have to check that the user has perms to actually (for example) approve RDFs before saying there are RDFs to approve, naturally, but damn that could be useful.

And now more bugs, maybe.

• For ads, when they use up their last impression, are they supposed to keep "Active" status? They do stop showing, as they should, but they are still marked as active ads in the system.
• When you edit an existing ad from the ad list, the ad edit form comes up with two buttons, "save" and "get"; when you go to the ad edit form using the "New Ad" link at the top of the ad admin page, the same form comes up, but with two different buttons, "create new ad" and "change template". The "Get" and "Save" button pair doesn't really make sense, since there isn't a drop-down list of the different ads (frankly, having "Get" there makes no sense at all). It should probably be handled something like the story edit form/new story form (ie, no "Get" button, just the "Save" button); the edit form is called up from the edit link next to the ad.

--
Discuss the art and craft of writing

• the var queue_edit_max_time was in the General category, not the Stories category where it belongs. Took me ages to find the thing when I was trying to figure out what it was called.
• the var editorial_comment_default has a completely wrong description. It sets a default, it doesn't turn the ability for an admin to toggle comment modes on or off.
• it would be nice if the perms were sorted somehow. Even alphabetically would make things so much easier to find...
• There are a lot of oddly-named things that I suspect are left over from the early (read: slash) days, such as editorial comments being marked behind the scenes as "pending" and the number of ratings a comment has being stored in a column called "lastmod".

--
Discuss the art and craft of writing

• max_rdf_intro doesn't appear to be used anywhere. The perlpod documentation in Cron.pm claims that it's used, but it appears nowhere else in that file, or anywhere else in the lib/ directory, for that matter. Nor is it in the database, except to define its existence.
• The page title for Site Controls is "Admin Vars" in the browser title bar, but "Site Controls" in the page itself.
• the var digest_subject should probably be a block, and stored alongside digest_headerfooter and digest_storyformat, just to make it easier to find.

--
Discuss the art and craft of writing

• the box section_title_subsections doesn't check section perms; if you have a section that hides its existence, and the user goes to the section index page, Scoop says "I can't find that section" (as it should) and displays the path to that section (as it shouldn't).
• auto-posted stories (posted with section perms, not with the queue auto-post timeout) still show the "hopefully the other users will vote on your story". Probably should check if the story is posted, or placed in the queue, and display an appropriate message.
• Might want to change the "welcome to scoop" sidebar in the default database to point to scoop.kuro5hin.org/guide rather than the even more horribly outdated docs on sourceforge. Since the new docs will be eventually moved to scoop.k5, this will automatically point to the new docs when they're done.
• I think a css op would be nice, so us CSS junkies don't have to put our CSS in the head of each page, nor do we have to maintain files outside of scoop's web interface. All it would have to do, really, is return the contents of a block as if it were a standalone file, with filetype text/css. If nobody's done it by the time I'm finished all the documentation work I'm doing, I may do it myself because it doesn't sound all that hard.
• misc db cleanup: page colours, text colours and so on should be in a block, so they can be changed in one place and not in every _template block.

--
Discuss the art and craft of writing

• It would be nice if, when editing a single block, the links to other themes took you to that same block. It already does this if you're editing a block category.

--
Discuss the art and craft of writing

I'm putting instructions in the SAG, but a sentence or two (like, "To create a new ad, first create its template using the Blocks Admin Tool" on the Ad Properties page or something...

--
Discuss the art and craft of writing

Another missing var: ads_in_everything_sec

Although, that should probably be replaced by adding the ad section to the new sections_excluded_from_all var.

Also, anybody who set up a new scoop site after the subscriptions stuff went in doesn't have the subscriptions patch applied, because it never went into scoop.sql. There are a few patches that never made it into scoop.sql, as I'm finding on my dev site (which gets its database nuked and reloaded from scoop.sql regularly).

--
Discuss the art and craft of writing

Missing db items:

• The entire subscription patch (0.8-0.9/patch-41) was not applied to scoop.sql; any Scoop installs created after that patch was put in CVS do not have any subscription functionality.
• The blocks subscribe_denied_message and subscribe_intro_text are not in patch 41 or scoop.sql.
• The perms allow_subscription and sub_allow_group_change are not in patch 41 or scoop.sql.
• The perm subscription_admin is also not present in scoop.sql, and while it is in patch 41, it's an old patch and tries to put the perm in the block "perms", which would be why my dev site doesn't have that perm even after applying the subscription patch. That'll have to be taken into consideration when making a new patch to update any sites that were created after the patch went through.

Errors in behaviour:

• For manual subscription activation, the URL is wrong; the code doesn't put a / between |rootdir| and user/uid:n.
• The code doesn't check the allow_subscription perm when displaying the "why don't you become a subscriber" link on the user info page.
• I can't find any place in the code where people are moved back to the non-subscriber user group when the subscription is over, but that may just be that I wasn't looking in the right place. All I could find was the removal of the subscription userprefs (subscriber, subscription_expire, and showad which should be a perm for a subscription group, not hard-coded).
• When a group can make subscriptions but can't be moved automatically to another group, things work as expected; when they can be moved automatically to another group, they are correctly moved but their confirmation email is not sent. When they extend their subscription, their confirmation email is sent properly. The error message in the logs when the confirmation email is not sent (for a new subscription only) is: (Scoop::mail) Error sending mail: No recipient! The realemails for both test accounts existed and were active to receive mail when this message appeared.

--
Discuss the art and craft of writing

Yeah, I know I did this. Anyway:

The link to a specific var from the category pages doesn't always work. I think it should be modeled after the blocks; with admin/tool/mode/item instead of just admin/tool/category as it is now. Then you could say edit/block_name or category/General and get the single block form or the category list, respectively.

Also, while that's being fixed, could the edit form be made bigger? Now that there is a textarea var type, stuff like perms is just a nightmare to edit in the little 3-line space that's currently there.

I am now starting on documenting the site controls. Look for an sql patch that will update the descriptions of all the standard scoop vars, coming soon. (Documentation for individual vars, blocks, and boxes will be in those items' description fields on your site, not in the SAG.)

--
Discuss the art and craft of writing

Documenting vars now; finding some strange stuff.

• advertiser_group, and req_extra_advertiser_info: does this work? I see code to handle it, but the /newuser/advertiser must be added to the op template before it'll go anywhere at all. I suppose once it's set up, with the ad submission perms set correctly, it looks like it should work just fine. (Of course, how to combine subscriber groups with advertiser groups... that's an interesting question.)
• looking at the graphical ad code, it appears to work. I figured out the settings that would allow me to create an example ad (namely, setting the ad_server_url and ad_files_base so the urls worked out), but the user-submitted ads have a few bugs.
  • The box that displays the ad when previewing it in submitad and in the ad judging page (show_ad) calls get_ad_hash, and expects one of the hash elements it returns to be "sponser", the UID of the user submitting the ad. Since it isn't in the hash, and the box uses that empty value to create the path, we end up with /images/ads//2373390.jpg instead of /images/ads/2/2373390.jpg as it should be. (assuming UID 2 is the sponsor).
  • For displaying the ad in normal rotation, the box ad_box gets a hash containing the sponsor info, but doesn't substitute it into the FILE_PATH special key. Once those two things are fixed, graphical ads almost work.
  • There's still the issue of the file upload only working on submit ad step 4 (because file uploads are handled by $S->save_ad), when step 3 is the preview step (leaving people to think it's horribly broken, which it is). If you preview for text and links, then fill in the image filename and hit "Purchase" instead of "Preview" it'll upload properly and work like a charm from there on.
• The ad approval email sends an empty field for the title even if there is no title in the ad template. It correctly hides the other fields (such as TEXT2).

--
Discuss the art and craft of writing

remember how site_url absolutely must not have a trailing slash, or any links sent out in email would break due to the double-slash? Well, ad_server_url is exactly the opposite; if you leave the slash off, it squishes the path into the URL and you get a different kind of breakage.

All URLs shouldn't care whether or not the var ends with a slash, because they should all strip any slash off (if present) and manually ad a slash in. That guarantees no mysterious breakages due to a misplaced slash, which is quite probable with all that inconsistent behaviour.

--
Discuss the art and craft of writing

The box "related_links" which creates the sidebar box looks for a block called autorelated to get its autorelated info from. If you're using CVS (or any version of Scoop with theme support), autorelated has been moved to a var. The box will have to be changed:

$S->{UI}->{BLOCKS}->{autorelated}

will have to become

$S->{UI}->{VARS}->{autorelated}

That is all.

This is also my fault because I moved autorelated to vars and didn't think to check if any boxes called it.

--
Discuss the art and craft of writing

While I'm on the subject of what belongs where, I'm wondering if stuff like the slogan var should be in blocks, where it can be subject to any internationalization that gets done.

Documenting vars is slow. I've just finished the vars beginning with "a". Oh well, I'm finding out for the first time how some of them interact, so it's only mostly boring instead of entirely boring. Plus I'm finding lots of bugs :-)

--
Discuss the art and craft of writing

The variable hide_unposted_comments currently only hides comments attached to stories in the queue or hidden in the search results. I think it should probably also affect comments requested directly via /comments/(sid) - either that or a second var added to do that. Some sites (mine included) may want to have hidden stories vanish with their comments, not leave the comments behind. Having such a var may clobber hidden sids, or may not... since front page post is displaystatus 0, and a hidden sid will be missing an entry, a hidden sid won't have a displaystatus<-1...

Also, Scoop really shouldn't tell a new user that their email is bad when the error is on Scoop's end - such as when the admin forgot to set local_email properly. It's not nice to blame the wrong person. I would consider that a bug.

--
Discuss the art and craft of writing

So, I was documenting keep_sessions_for yesterday, and I said that it determined how long somebody had to be away before the session was expired. The sessions table has a last_accessed column, and the sessionreap cron checks that value against the current date. So, one would assume that on every page request, the last_accessed date is updated and my description was correct, right?

Well, I can't find the code that updates the last_accessed field, and my live site (which I visited yesterday) logged me out this morning when I checked it - implying that the last_accessed date is set when I last logged in, and not updated when I last accessed the site.

Is this a bug, a misconfiguration, or a misunderstanding? Is sessionreap supposed to log people out, even if they accessed the site more recently than keep_sessions_for, once they've been logged in longer than keep_sessions_for?

--
Discuss the art and craft of writing

• There's a var called strict_introtext_limit in the code (and not in the db) which turns on and off a "maxlength" attribute to the introtext TEXTAREA field. Only textarea fields don't have a maxlength attribute. Should probably be removed, just so nobody finds it and tries to use it.
• the variable max_rdf_intro is used in the code as rdf_max_intro. Which one should I document?
• min_ad_prepay_amount does not appear in either the code or the database, except as a var where it is defined. Is this another var-name mixup like the above rdf var?
• why is the default value of mojo_min_untrusted 3.5? It represents a number of comments, and I'd expect it's rather hard to have a half of a comment...
• perms. The fact that removing a perm from the perms var removes it from the groups admin tool is ok, if unintuitive; that those removed perms are still granted to groups that had them before is just awful. Removing a perm should also disable it. Personally I think perms should be stored in a table rather than as a comma-separated list, because then you could actually do stuff like that.
• the var poll_img_width is missing from the db and all patches. Just thought you'd like to know :-) (it defaults to 300 in the code)
• in the polls admin, it does check that the person editing the poll is an admin before letting them edit the number of answers, but it doesn't check if the var "allow_ballot_stuffing" is on.
• I have an idea, lets make the textarea you're supposed to edit special pages in a bit bigger. Yeah, I know about boxtool, but if I just want to make a small change...
• when scoop returns a "sorry, I can't find x" page, can it also return a 404 header? You know, just so stuff like search engines know that it's gone and so they don't think it's a page with the content "sorry, I can't find x"?

--
Discuss the art and craft of writing

• scoop doesn't check if rating_wipe_group exists before changing a user to that group. That is, it checks that the *var* exists, but not if the *group* exists. What happens when a user is placed in a nonexistant group?
• there's a var and a function to display the recent topics (slashdot-style) but no box to easily place on the index pages.
• diaries and adverts should use sections_excluded_from_all to keep them out of __all__ and the RDF feed. I know it's a new var and nobody's had a chance to fix this yet, I'm just putting it here so there's a record and a reminder for anybody doing coding.
• when displaying the front and everything pages, does scoop check whether the user has permission to see each story based on its section? or is the admin expected to add sections banned to some groups to exclude_sections_from_all which hides them from all groups?
• the story department doesn't check if somebody's actually entered something into the field... so if a site switches from not using it to using it, all previous stories will be "from the department"
• show_new_comments has 3 possible text values, according to the description, but in lib/Scoop/Comments/Format.pm and lib/Scoop/Comments.pm it is used as a toggle - so since even "never" exists when tested that way, those two modules will always display the new comment marker. Actually, they'll only behave 100% properly when show_new_comments is set to "all".

--
Discuss the art and craft of writing

• spellcheck is disabled for anonymous users (uid <= 0) regardless of permissions
• when determining whether or not the spellcheck box is checked, if a user's default is to use spellcheck and he unchecked the box for a preview, the box is checked again after the preview.
• template_recurse sounds like a great idea and looks like it should work, but I remember a block accidentally getting a reference to itself as its content (part of the themes patch, IIRC) which resulted in the apache server gobbling up all kinds of resources and never returning a page. Not sure if this has been fixed or not. Also, looking a bit deeper, the interpolate function is run once for every template_recurse, no matter how large you set it, and it always manages to find a lot to interpolate... at least according to the debug output.
• html parser bug? the "less than" symbol in the first bullet point was displayed and made the following <LI> tag display instead of having its usual effect. I had to change it to &lt; to fix. (Yeah, ok, if I'm posting in html formatted mode, I should take care of special characters myself. But considering that the html mode doesn't even require proper use of the P tag...
• also, in the above item, the &amp; used to display the & in &lt; was changed to just a & so on the next preview only &lt; was displayed. And I'm going to continue my bugs in another comment, because I'll be damned if I'm going to keep correcting the changes...

--
Discuss the art and craft of writing

• the variable topic_images_default (added in patch 12, of current) is not in the default scoop database.
• handling of topic display is kind of wacky, IMO.  You have a variable to turn topics on or off entirely, and to display topic images or not, and a user pref for images or not... but unless the admin changes |topic_img| to |topic_text|, choosing not to display topic images means that no topic information is shown at all. And if the admin changes it to |topic_text|, nobody gets images. What I think it should be, is if topics are enabled and topic images are off, the topic text should be shown instead, not nothing at all.

--
Discuss the art and craft of writing

• upload_max_file_size does not appear to be actually used in the code.  It fills a variable with its value, but the code which uses that variable to test the file size has been commented out.  The function returns the size of the file, which also does not appear to be used anywhere, except to define a variable with the value.
• real_initial_rating is used in the code but is not present in the database or any patch.

• advertiser_group appears in the code but is not actually used.  This was mentioned earlier, when discussing the whole "extra advertiser info" thing.
• allow_ad_renewal seems clear enough but when I was testing ads, it didn't seem to put a renew link on the user's ad page.
• what versions of which browsers support dynamic comments properly?
• box_title_font and box_title_font_end should be blocks
• default_uid is not used in the code or the db anywhere, according to grep
• min_ad_prepay_amount is not in the code or the db anywhere, according to grep
• mojo_min_untrusted has a default value of 3.5 even though it's supposed to be a number of comments
• op_aliases and op_templates are changed in hillct's op_templates patch; I don't really want to document them in vars if they're going to be moved shortly, so I haven't yet
• the box that displays recent topic images (and uses recent_topics_num) is not included in scoop by default, nor is it in the sbe
• sections_excluded_from_all should include diaries and ads.  This will involve a fair bit of rewriting to take all the hardcoded diary stuff out of the code.
• slogan should be moved to blocks
• template_recurse doesn't work properly
• use_topics behaviour is weird; suggestions made earlier to improve

--
Discuss the art and craft of writing

• So, how does static page caching and themes interact?  The content and basic layout of the page are saved in the file, but blocks such as the fonts, and the header and footer, and all the sidebar boxes remain to be interpolated.  The section theme won't change; the pages are only sent to anonymous users, so the group and userpref themes won't change; the user agent theme, however, may, as well as any other theme criteria that may be added by an individual site.  Of course, that may not be worth worrying about.
• for location-based installs, dynamic-comments.js and backend.rdf are saved to the correct directory, but as there is no location-based equivalent to the vhost "documentroot" directive in the scoop location config files the files cannot be fetched from the internet unless placed in the images directory (or another directory set up in the same way).  There doesn't appear to be any mapping between the base scoop directory and a filesystem location at all, in the location-based install.
• do we even use any of the SourceForge features (apart from the mailing lists) anymore, now that CVS has been moved to versionhost?  I see a couple of bugs reported this year, but ...
• speaking of SourceForge, I suggest the (horribly old) docs there be removed and a link added pointing to the docs here.
• can somebody address the stuff in the previous comment so I can submit the var documentation patch?  Thanks...

--
Discuss the art and craft of writing

• digest email blocks use __key__ instead of |key| and literal n instead of a return.  A holdover from the old days; can probably be updated to make things easier for the admins.
• could use a pref allowing users to choose whether they want new comment tracking, instead of just admins.  Well, don't allow them to track more than the admins allow, but allow them to turn it off or choose something up to what admins allow.
• add a force preview option for comments, as for stories?  I see a few double-posted comments because the user forgot to preview and make sure the formatting was even remotely correct.

--
Discuss the art and craft of writing

I found it while I was looking at moving the story vote form out of the code so I could change the labels in the drop-down box for my site :-)

Back to the tour of the solar system later...

--
Discuss the art and craft of writing

• when calculating the overall comment score, hidden comments are ignored - with a hard-coded "1" in the query, instead of a call to the rating_min variable.
• the auto-post algorithm uses four seperate selects, one to get the count for each of the four possible votes. This struck me as remarkably silly, so after about half a minute of mucking around, I came up with the following single query that returns counts for each of the possible four votes (if one of the possible votes has not been used, no row will be returned for that vote option):

--
Discuss the art and craft of writing

• the poll_archive cron is set to run once every minute. That's got to be a typo; I can see it running once a month... (m vs. M)
• a bunch of missing blocks, listed below.

• commentswarning
• donate_email_pledge
• donate_email_success
• dynamicmode_iframe
• dynamicmode_javascript
• new_story_flag
• next_previous_links
• rating_format
• subtitle (possibly dynamically generated by scoop)
• file (called in Debug.pm only, probably not really a missing block)
• line (as above)
• package (as above)
• thetime (as above)

And now I will start creating documentation for blocks, as I have done for vars.  I will also fix the confusing category layout in blocks. (Yes, that category layout was my fault.  I'm sorry to anybody it confused.  I'm pretty sure it made sense at the time, but I'm not sure anymore what kind of sense...)  I think something closer to what was done with the var categories is in order.

• Is forumzilla used by anybody? Does it even still work?  Might be worth taking the fz blocks, vars, and code out...
• if the advertising_account_disclaimer is only used in the form that collects extra advertiser info (new_advertiser_html), why is it separated out? Why not just have it all in one block?
• The code that handles the special keys for ad_approval_mail seems to handle a field called "impressions", which is not in the list of fields fetched from the database (and does not exist in the database in the ad_info table in any case).  Found this while trying to figure out if this was "impressions remaining", "impressions used", or "impressions purchased"...
• the block ad_renewal_mail says that "your ad has been renewed", the code that calls it says it's a notice that the ad should be renewed, and that particular function is never actually called anywhere in the code or in a box.  Yet another unimplemented ad feature?

--
Discuss the art and craft of writing

Now that ops support just running boxes, the old-style boxy ops should be converted (that is, the ones where the op designates no code and a special page template, which calls a box).  Namely:

• buyimpressions_box
• fzdisplay
• renewad_box
• submit_rdf

Ok, more stuff:

• there's a block to mark comments by members of a particular group (mark_groupname) but it is only used if the user has an active subscription.  This seems counterintuitive to me... if it's subscription based, it should mark based on subscription; if it marks on group, it should mark everybody of that group.
• in the comment block, the special key "user_info" contains the value of the special key "edit_user", even though "edit_user" is recognised as a separate special key
• comment_posted_message is not self-contained at all.  It ends by opening a new <TD> of all things.  This will need to get fixed along with the rest of the html removal from the code.  I don't know how easy it'll be, that particular table is scattered all over. Though on thinking about it a bit, one new block with two special keys would probably take care of it.

--
Discuss the art and craft of writing

• digest_subject is in blocks, but the code looks in vars... (Cron.pm)
• for dynamic_loading_link and dynamic_loading_message: I'm not entirely sure what the distinction is, since they're both displayed while a dynamic comment is being loaded.
• the code says the var (?) mainpid (in dynamic comment mode) is no longer used, and actually isn't, the only place it appears is to set it to zero. Could this be taken out of the dynamic_template without breaking things?
• how on earth does the key dynamicmode get interpolated into dynamic_template? it's not a block, not a var, I can't find it in the code... the only thing left is that it gets done in javascript, which I don't know how to read. If somebody could explain this to me so I can document it, it would be much appreciated.
• The blocks admin tool should get that /g on its description special key, same as vars did, so you can have the formatted description as well as the editable description. (Blocks.pm, line 250)

Note to self: make sure, when doing the "hacking Scoop" part of the docs, to mention the assert() and interpolate() functions, because they're hardly used. They're hardly used because nobody knows about them except the person who wrote them...

--
Discuss the art and craft of writing

• mail_ad_almost_done and mail_ad_done (and all the other ad email notices that use the escape_adjudge_mail function for their special keys) can only handle the title/url/text style of ads used by k5, even though the ad code itself can handle ads with two text fields and ads with images.
• new_user_html is placed between some code-generated <TABLE> tags. ick. That probably won't be hard to clean up.
• the norm_font thing - this is probably partly related to user pref flexibility, but if an admin wants to get rid of the ridiculous number of font tags in the scoop HTML but still allow the users to customize the font and font size, this'll need cleaning up. I'm not sure if it can be done like this already because I haven't looked that closely at the code, but this may work: have site-wide variables default_size and default_face which the user preferences override (would the blocks norm_font_face and norm_font_size do this?) then use those two overrideable variables in either norm_font or a stylesheet, whichever the admin likes better.
• in lib/Scoop/Ads/Submit.pm, the if structure starting at line 50: the value '5' isn't caught.
• why are paypal_canceled and sub_paypal_canceled different blocks? They're both doing the same thing, except one is used for ads and the other for subscriptions. They really should be the same block, so payments for anything via paypal can use them. May be worth having one message for all payment cancelled events, regardless of payment method or subscription/ad/whatever...
• pendingstory_bg doesn't appear to be used anywhere in the code or any box.
• in poll_block, it uses the special key |hotlist| but based on my reading of the code, that isn't a valid special key for polls. Also, when viewing a poll, there is no hotlist link. the special key |info| isn't used either.
• The block poll_box isn't used as a box template for the box poll_box. The box poll_box uses the plain box template. Might as well take it out of scoop.sql so it doesn't confuse anybody
• poll_guidelines isn't used anywhere. The block attach_poll_message does what I suspect this was intended to do. Might as well remove it.
• preview_text_ad_template isn't used anywhere.
• ad renewals seems to be broken. It won't even give you a renewal link if the ads are free. The ad code that creates the initial link to the ad renewal page checks to see if the ad has been paid for (on first glance, it should probably check to see if it's active, to allow for sites with free ads). Typing in the correct URL to the ad renewal page or editing the ad so it's marked paid seems to work, but in both cases the number of impressions is not updated, you are shown the "this ad has to be approved" - kind of silly, since the ad has already been approved if it's active, and you can't change anything about the ad except how long it runs when renewing - and there's no indication on the "your ads" page that you need to pay anything.
• when creating a new ad template (I have the steps all laid out in the SAG) the properties are set but it cannot be saved as active until there is an example ad. When saving the properties, even if the 'active' checkbox is unchecked, it displays an error message saying it can't be activated. That error should only be displayed if the admin tried to save it as active when there was no example ad yet.
• renew_confirm_message is not used. The block confirm_ad_renew is used for that purpose.

--
Discuss the art and craft of writing

• story_info uses a special key (comment_controls) that is not recognised. That would confuse people.
• what on earth is going on with the story list colours? we have undisplayedstory_bg (which you'd expect to be used for stories that are hidden) being used for those, the current poll in the poll list, and stories the user hasn't voted on yet in the edit categories queue list., and submittedstory_bg being used for both stories in the voting queue and for RDF feeds that haven't been approved yet.
• the block subscribe isn't used anywhere. Some very similar text is hard-coded in Subscription.pm.
• subscribe_intro_text has a default value in the code, but it's in scoop.sql and it's been added in a patch now, so it doesn't really need to have a default value in the code. (Subscription.pm)

--
Discuss the art and craft of writing

There aren't any new blocks in the patches, but I see a couple of macro-system related blocks in scoop.sql. Not sure how that works, because I can't find the code for it anywhere in my dev site. Looking at the checkin message, I think those blocks were put into scoop.sql by accident, since the checkin message only mentions the new whos_online box.

Anyhow, there are a few issues with blocks (listed in my last few comments, comments #46-50)), some of which I would like to see resolved before submitting the patch. Even if the resolution is just to delete the block (which should happen in a few cases).

The quick summary of those issues is:

• in all ad emails, a field 'impressions' is requested but does not exist in the database and is never used
• there are 4 old-style box ops that should be converted. (the op has no function associated with it, but the page template calls the box instead of having |CONTENT|)
• mark_(groupname) is only used if the user has an active subscription; should be purely based on group.
• in comment and moderation_comment, the special key user_info includes the content of the special key edit_user, which can be placed separately.
• dynamic_loading_link and dynamic_loading_message... not sure what the distinction is
• pendingstory_bg isn't used. Remove it?
• poll_box is a box template that isn't actually used for any boxes, at least in scoop.sql. Not sure about other older sites, but mine doesn't use it after the latest patches either. Remove it? Or just remove it in scoop.sql?
• poll_guidelines aren't used. a different block is instead. remove?
• forumzilla - can that entire subsystem go? I've never heard of it being used at all, and I don't know if it's even been tested.
• the block subscribe isn't used. The code should probably be altered to use it, instead of the very similar message hardcoded in.

--
Discuss the art and craft of writing

• the user_box should have a line that checks the upload_user and upload_admin perms to add or hide a line "Your Files"
• the file uploads page shows subdirectories as files. Directories should either not be listed, or should be handled as directories and not files.

Oh, and the autoformat code got broken at some point. It won't linkify bare URLs anymore, as of a few months ago. It will still linkify square-bracketed URLs properly. The change seems to be related to the fix for URLs that had http in them, or something. The most recent bugfix for the autoformat regexp.

--
Discuss the art and craft of writing

• Go to /user/scoop (or other valid username) while logged in as superuser. Click on the [edit user] link. Nothing happens. ?op=user;tool=prefs;uid=1 seems to display user info as well, instead of user prefs. This doesn't happen on my 4-month-old install, but does on my default CVS dev site with last week's code.
• Increment the uid number in the user info page. No error message is displayed, just a blank "'s info"
• Where's that anonymizer function thing?

• user_new shows up twice in Admin/Users.pm
• There are 14 distinct run_hook commands in the code (counting the double user_new as one) but only 11 hooks listed in the hooks var. The missing hooks are: comment_toggle(sid,cid,tool), file_upload(path), and user_confirm(nick)

Subsections.

• For some reason I'm still not clear on what the hell the 'invisible' property is supposed to do to a child section. 'inheritable' I get, it means the parent section(s) gets its stories too.
• Is there a function that'll return a list of a section's children? If there is I can't seem to find it, and that seems like a remarkably useful thing to have if a site wants to set up a simple heirarchical section structure.

And if anybody cares, the SAG now weighs in at about 36,000 words, or 83 pages (excluding title page and TOC) when LaTeX does its thing.

--
Discuss the art and craft of writing

• subpay_paypal and ad_pay_paypal both use a paypal account name/email in the boxes - this would work well as a var. Then you only have to change it in one place...
• nonexistant vars ads_use_cc and ads_use_paypal. These are required to use payment processing
• submit_ad_pay_box should be modified to show whichever payment options have been turned on by the two missing vars above, instead of neither.
• subpay_type_select refers to K5 in the cc logo alt text, and displays "you can pay by paypal or cc" without checking the two missing vars above to see whether you actually can use both payment methods.

--
Discuss the art and craft of writing

I also have to do box descriptions, I guess. :-)

In the block descriptions, I still have a whopping four questions; all the others have been resolved. The block description patch will be coming in very soon. (Three of the questions have to do with dynamic_loading_message, dynamic_loading_link, and the dynamicmode key in the block dynamic_template. The fourth question, an answer has been promised me already.)

So yes, I have found more bugs.

• In Scoop/DB.pm: db_delete and db_update both use LIMIT, but my MySQL manual says that LIMIT only applies to selects.
• code for donations and pledges is present in the backend, but there are no boxes in the database for you to place on the page. Also, paypal_confirm doesn't know about donations. By default it doesn't know about subscriptions either, but I believe panner is fixing that or has fixed that in one of his recent patches.
• there is a variable ads_use_paypal that turns the "pay with paypal" on and off for ads, but nothing corresponding to this for subscriptions. The subscription payment page shows both paypal and CC links, regardless of which you're using.

--
Discuss the art and craft of writing