SectionTopics

From SoylentNews
Revision as of 21:55, 28 February 2014 by 50.45.173.59 (talk) (Created page with " NAME sectiontopics - Information about the section-topics rewrite, June 2004 DESCRIPTION In June 2004, the way Slash handles categorization of stories into topic...")

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

NAME

   sectiontopics - Information about the section-topics rewrite, June 2004

DESCRIPTION

   In June 2004, the way Slash handles categorization of stories into
   topics was changed. The confusing relationship between topics, sections,
   and subsections, which limited choices, was bolted on to the old system
   as our needs evolved.
   The "section-topics" rewrite, as it's being called, took a look at those
   needs with the perspective of hindsight, and developed a new system
   which will be less confusing in the long run. It provides the
   flexibility that large sites' admins will need, while still retaining
   ease of use for smaller sites' admins.
   This document attempts to explain the changes for Slash administrators,
   and it may be informative reading for Slash authors and editors too.

CONCEPTS

   I'm not going to bother explaining exactly how the old system worked,
   because it's dead now. Suffice it to say that every story had one
   section and one or more topics, those being two distinct and disjoint
   categorizations. Subsections were invented to allow finer-grained
   control than what sections permitted, and there were ways to constrain
   certain topics to only being available in certain sections.
   The "section" data type was always confused about whether it wanted to
   be a categorization and descriptor, or a visual display modifier. In
   other words, regarding an object that it was assigned to like a story,
   "section" implied facts about both its data and how it should be viewed.
   Being in the "Book Reviews" section on Slashdot, for example, implied
   that additional data like ISBN would be stored along with the rest of
   the story's data. Being in the "Developers" section meant that it would
   be grouped with other developer-related stories and that it would appear
   blue instead of green. If a story was a book review for developers,
   there was no way to put it in both places; having that blue color meant
   that no ISBN data could be stored.
   So "section" has been split into two: "skin" and "nexus". *Most* of the
   information that went with a section was used to describe appearances,
   and that went over to skin. So a skin now controls color (through the
   skin_colors table), it controls which templates are used (the final part
   of a template's three-part name is now skin, not section), and it
   controls with which other stories a story is grouped (on which index
   page). And the non-display aspects of sections -- mainly, the
   "section_extras" data which ensured that stories in Book Reviews stored
   a field for ISBN -- were sent over to nexuses.
   Each skin has precisely one nexus; you can think of a skin as drawing
   its stories from its nexus. The clever part is that a nexus is just a
   special kind of topic (which we call a topic_nexus when we want to
   emphasize that it is both). So if a story has both the Developers
   topic_nexus, and the Book Reviews topic_nexus, then it will appear on
   both books.slashdot.org and developers.slashdot.org. And the additional
   data stored with the story will include the union of all the "extras"
   data -- not only ISBN and so on, but also any "extras" data that may be
   in the Developers nexus. There don't actually happen to be any extras
   for Developers on Slashdot, so maybe this isn't the best example, but if
   there were, a story that was categorized into both nexuses would include
   that data too.
   Authors are no longer restricted from choosing any topic with any story.
   Since a nexus is a topic like any other, an author who wishes to make
   sure a story shows up in the Apple skin can pick the Apple nexus
   specifically. But what's more likely to happen is that an author will
   pick topics that make sense for the story (like "Mac OS X") and that the
   weights assigned to those topics will propagate upwards into the correct
   nexus(es) where the story should appear.
   Along the way, stories were given a numeric primary key (stoid), as were
   skins. Don't worry, a story's sid still works just as it did before; no
   Slash URLs are required to change, and in particular all the URLs (for
   search.pl and index.pl) that had "section=" as a parameter still do.

WEIGHTS

   Each topic picked for a story now must have a weight assigned to it.
   Weights are floating-point non-negative numbers. The templates shipped
   with the stock theme assume that authors will be assigning only the
   weights 0, 10, 20, 30, 40, or 50, but the only weight value that the
   core code treats specially is 0 (which means "ignore this topic"). How
   positive weights affect the categorization of stories depends entirely
   on the topic_parents table.
   Even in the old system, topics could be arranged into a tree -- but to
   properly represent section-specific topics one would have to layer
   additional data on top of the tree, confusing matters somewhat. Now,
   topics (including nexuses) really do form a tree, which is to say a
   directed graph. All topic-related data is loaded into a $slashd object
   at once, when getTopicTree is called.
   One key difference between the old system and the new is that,
   previously, a topic had at most one parent. Now, a topic may have zero
   or more parents. This allows a topic of "Darwin" to be a child of both
   "Apple" and "BSD," which conceptually means that it is a subcategory of
   both, and which practically means that assigning "Darwin" a weight will
   allow that weight to propagate up to both.

RENDERING

   This process of weight-propagation occurs when chosen topics are
   rendered. Each parent-child relationship from one topic to another
   includes a minimum weight. For any given story, if topic T1 is assigned
   weight W, and topic T2 is the parent of T1 with min_weight M, then T2
   will also be assigned weight W for the story if, and only if, M <= W.
   That assignment continues recursively (to topic T3, and so on) in a
   process called "rendering" -- performed by renderTopics(). A story
   author stores his or her topic/weight duples in the story_topics_chosen
   table, and at story save time, these choices are rendered into a
   (probably larger) collection of topic/weight duples that are stored in
   the story_topics_rendered table.
   (The above rule describes most of what is involved in the rendering
   process. The other rules in the algorithm are that if multiple children
   of differing weights both propagate up to the same parent, the greater
   of those weights become the parent's; and that any topic's chosen
   weight, including a weight of 0, always overrides any weight propagating
   up from its children.)
   Finally, when the collection of rendered topic/weight duples has been
   fully formed, all topics with weight 0 are dropped. Weight 0 can exist
   in chosen topics, but never in rendered topics.

A SIMPLE EXAMPLE

   That may sound a bit complicated, so here's a description using the
   default topics and topic_parents included with the default "slashcode"
   theme:
   tid 1: mainpage (also a nexus)
   tid 3: opensource (also a nexus)
   tid 4: slash
   tid 7: linux
   Tid 4 has tid 3 as a parent, with that relationship having a min_weight
   of 10 associated with it.
   Tid 7 also have tid 3 as a parent, with min_weight 10.
   Tid 3 has tid 1 as a parent, with min_weight 30.
   The skin at "http://example.com/" reads the nexus tid 1; the skin at
   "http://opensource.example.com/" reads the nexus tid 3.
   Suppose an editor is working on a story about Slash and assigns it the
   topic "slash," tid 4, with weight 10. Weight 10 is described as
   "Sectional only" in the code. When that story is saved, renderTopics
   recursively propagates the weight of its topics, or in this case its
   single topic, up to parents, or in this case parent. Rendering adds tid
   3, also at weight 10. It does not add tid 1 since !(10 >= 30). The story
   thus will appear only on "http://opensource.example.com/" and not
   "http://example.com/".
   Now suppose the editor re-edits the story, adding important information
   about Linux. He or she at that point adds the Linux tid 7 with a weight
   of 30. Now when it is saved, tid 1 is added since 30 >= 30. Now the
   story will appear at both URLs.
   Now suppose the editor is instructed that this story must be removed
   from "http://opensource.example.com/", though it should stay on the main
   page "http://example.com/". In the admin.pl editor, he or she adds tid 3
   with weight 0. That by itself would remove both nexuses when the story
   saves, since the 0 would prohibit both child tids from propagating
   higher than tid 3 up to tid 1. Upon clicking Preview, the admin sees
   that "This story will not appear" (see admin.pl
   getDescForTopicsRendered()). So the admin also adds tid 1 -- any weight
   greater than 0 would do, but weight of 30 makes the most sense since the
   backend describes that as "Mainpageworthy." Once this story is saved,
   its rows in story_topics_chosen are:
           tid 1, weight 30
           tid 3, weight  0
           tid 4, weight 10
           tid 7, weight 10
   and its rows in story_topics_rendered are:
           tid 1, weight 30
           tid 4, weight 10
           tid 7, weight 10
   Note that, as far as almost all of the code is concerned, the weight
   value in story_topics_rendered is irrelevant; only whether a row exists
   or not is noted. (This is why weight of 0 never appears in that table.)

DISPLAY OPTIONS AND WEIGHTS

   So how are these values of weights 10 and 30 decided, and what are 20
   and 50 for?
   Previously in Slash, there were three possible values for a story's
   displaystatus: Never Display, Section-Only, and Always Display.
   Section-Only meant to only display a story in its section's homepage,
   not the site's main page, and Always Display meant to display a story
   both places.
   Now that a story may be part of more than one skin (the new term for
   "section"), that distinction is not so simple. While the method
   _displaystatus() will return an old-style displaystatus value for a
   story, this is for reverse compatibility and is deprecated. The proper
   question now takes two arguments instead of one: is a story to be
   displayed _in_ a particular skin.
   The answer to that question is very simple; if a row exists in
   story_topics_rendered with the story's stoid and the topic's tid, then
   yes; otherwise, no.
   To prevent everything from breaking at once, and to keep the backend
   story list looking much the same as it did before (white background for
   Always Display, light gray for Section-Only, dark gray for Never
   Display), the "mainpage skin" was created. Defined by the var
   mainpage_skid [sic, a skid is a skin's numeric primary key], this
   defines which skin a story must be in to be considered "Always Display."
   It also defines which topic nexus will be colored blue instead of yellow
   in admin.pl?op=topictree (you will need GraphViz installed to see this;
   see plugins/Admin/README). Nevertheless, Slash is now well-equipped to
   run a website which consists of many subsites, at different URLs,
   perhaps only loosely networked and not necessarily with one central
   "main" page.
   multiple skins and how index.pl uses stories.primaryskid
   skins.cookiedomain and the cookiedomain var
   the Topiclist
   the topic chooser
   no admin.pl interface to edit topic tree yet, but op=topictree (and
   GraphViz, see plugins/Admin/README)
   suggestions for a clean topic tree (use min_weight 10 to connect
   many/most topics to logical categorizations, which could/should be
   nexuses, then connect those to mainpage with min_weight 30, finally
   bring loose topics to mainpage with min_weight 30)
   utils/convertDBto200406
   and _suggest and how it can be used to advise on a better topic tree
   and _render which needs to be run

VERSION

   $Id$

[root@slashcode docs]# [root@slashcode docs]# ls boilerplates HOWTO-Themes.html sectiontopics.txt slashstyle.txt dopods.plx HOWTO-Themes.pod slasherd.fig slashtables.html formkeys.txt HOWTO-Themes.txt slasherd.pdf slashtables.pod HOWTO-Plugins.html INSTALL.pod slasherd.ps slashtables.txt HOWTO-Plugins.pod INSTALL.txt slashguide.html slashtags.html HOWTO-Plugins.txt README.pod slashguide.pod slashtags.pod HOWTO-Templates.html README.txt slashguide.txt slashtags.txt HOWTO-Templates.pod sectiontopics.html slashstyle.html HOWTO-Templates.txt sectiontopics.pod slashstyle.pod [root@slashcode docs]# more sectiontopics.txt NAME

   sectiontopics - Information about the section-topics rewrite, June 2004

DESCRIPTION

   In June 2004, the way Slash handles categorization of stories into
   topics was changed. The confusing relationship between topics, sections,
   and subsections, which limited choices, was bolted on to the old system
   as our needs evolved.
   The "section-topics" rewrite, as it's being called, took a look at those
   needs with the perspective of hindsight, and developed a new system
   which will be less confusing in the long run. It provides the
   flexibility that large sites' admins will need, while still retaining
   ease of use for smaller sites' admins.
   This document attempts to explain the changes for Slash administrators,
   and it may be informative reading for Slash authors and editors too.

CONCEPTS

   I'm not going to bother explaining exactly how the old system worked,
   because it's dead now. Suffice it to say that every story had one
   section and one or more topics, those being two distinct and disjoint
   categorizations. Subsections were invented to allow finer-grained
   control than what sections permitted, and there were ways to constrain
   certain topics to only being available in certain sections.
   The "section" data type was always confused about whether it wanted to
   be a categorization and descriptor, or a visual display modifier. In
   other words, regarding an object that it was assigned to like a story,
   "section" implied facts about both its data and how it should be viewed.
   Being in the "Book Reviews" section on Slashdot, for example, implied
   that additional data like ISBN would be stored along with the rest of
   the story's data. Being in the "Developers" section meant that it would
   be grouped with other developer-related stories and that it would appear
   blue instead of green. If a story was a book review for developers,
   there was no way to put it in both places; having that blue color meant
   that no ISBN data could be stored.
   So "section" has been split into two: "skin" and "nexus". *Most* of the
   information that went with a section was used to describe appearances,
   and that went over to skin. So a skin now controls color (through the
   skin_colors table), it controls which templates are used (the final part
   of a template's three-part name is now skin, not section), and it
   controls with which other stories a story is grouped (on which index
   page). And the non-display aspects of sections -- mainly, the
   "section_extras" data which ensured that stories in Book Reviews stored
   a field for ISBN -- were sent over to nexuses.
   Each skin has precisely one nexus; you can think of a skin as drawing
   its stories from its nexus. The clever part is that a nexus is just a

[root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# [root@slashcode docs]# cat sectiontopics.txt NAME

   sectiontopics - Information about the section-topics rewrite, June 2004

DESCRIPTION

   In June 2004, the way Slash handles categorization of stories into
   topics was changed. The confusing relationship between topics, sections,
   and subsections, which limited choices, was bolted on to the old system
   as our needs evolved.
   The "section-topics" rewrite, as it's being called, took a look at those
   needs with the perspective of hindsight, and developed a new system
   which will be less confusing in the long run. It provides the
   flexibility that large sites' admins will need, while still retaining
   ease of use for smaller sites' admins.
   This document attempts to explain the changes for Slash administrators,
   and it may be informative reading for Slash authors and editors too.

CONCEPTS

   I'm not going to bother explaining exactly how the old system worked,
   because it's dead now. Suffice it to say that every story had one
   section and one or more topics, those being two distinct and disjoint
   categorizations. Subsections were invented to allow finer-grained
   control than what sections permitted, and there were ways to constrain
   certain topics to only being available in certain sections.
   The "section" data type was always confused about whether it wanted to
   be a categorization and descriptor, or a visual display modifier. In
   other words, regarding an object that it was assigned to like a story,
   "section" implied facts about both its data and how it should be viewed.
   Being in the "Book Reviews" section on Slashdot, for example, implied
   that additional data like ISBN would be stored along with the rest of
   the story's data. Being in the "Developers" section meant that it would
   be grouped with other developer-related stories and that it would appear
   blue instead of green. If a story was a book review for developers,
   there was no way to put it in both places; having that blue color meant
   that no ISBN data could be stored.
   So "section" has been split into two: "skin" and "nexus". *Most* of the
   information that went with a section was used to describe appearances,
   and that went over to skin. So a skin now controls color (through the
   skin_colors table), it controls which templates are used (the final part
   of a template's three-part name is now skin, not section), and it
   controls with which other stories a story is grouped (on which index
   page). And the non-display aspects of sections -- mainly, the
   "section_extras" data which ensured that stories in Book Reviews stored
   a field for ISBN -- were sent over to nexuses.
   Each skin has precisely one nexus; you can think of a skin as drawing
   its stories from its nexus. The clever part is that a nexus is just a
   special kind of topic (which we call a topic_nexus when we want to
   emphasize that it is both). So if a story has both the Developers
   topic_nexus, and the Book Reviews topic_nexus, then it will appear on
   both books.slashdot.org and developers.slashdot.org. And the additional
   data stored with the story will include the union of all the "extras"
   data -- not only ISBN and so on, but also any "extras" data that may be
   in the Developers nexus. There don't actually happen to be any extras
   for Developers on Slashdot, so maybe this isn't the best example, but if
   there were, a story that was categorized into both nexuses would include
   that data too.
   Authors are no longer restricted from choosing any topic with any story.
   Since a nexus is a topic like any other, an author who wishes to make
   sure a story shows up in the Apple skin can pick the Apple nexus
   specifically. But what's more likely to happen is that an author will
   pick topics that make sense for the story (like "Mac OS X") and that the
   weights assigned to those topics will propagate upwards into the correct
   nexus(es) where the story should appear.
   Along the way, stories were given a numeric primary key (stoid), as were
   skins. Don't worry, a story's sid still works just as it did before; no
   Slash URLs are required to change, and in particular all the URLs (for
   search.pl and index.pl) that had "section=" as a parameter still do.

WEIGHTS

   Each topic picked for a story now must have a weight assigned to it.
   Weights are floating-point non-negative numbers. The templates shipped
   with the stock theme assume that authors will be assigning only the
   weights 0, 10, 20, 30, 40, or 50, but the only weight value that the
   core code treats specially is 0 (which means "ignore this topic"). How
   positive weights affect the categorization of stories depends entirely
   on the topic_parents table.
   Even in the old system, topics could be arranged into a tree -- but to
   properly represent section-specific topics one would have to layer
   additional data on top of the tree, confusing matters somewhat. Now,
   topics (including nexuses) really do form a tree, which is to say a
   directed graph. All topic-related data is loaded into a $slashd object
   at once, when getTopicTree is called.
   One key difference between the old system and the new is that,
   previously, a topic had at most one parent. Now, a topic may have zero
   or more parents. This allows a topic of "Darwin" to be a child of both
   "Apple" and "BSD," which conceptually means that it is a subcategory of
   both, and which practically means that assigning "Darwin" a weight will
   allow that weight to propagate up to both.

RENDERING

   This process of weight-propagation occurs when chosen topics are
   rendered. Each parent-child relationship from one topic to another
   includes a minimum weight. For any given story, if topic T1 is assigned
   weight W, and topic T2 is the parent of T1 with min_weight M, then T2
   will also be assigned weight W for the story if, and only if, M <= W.
   That assignment continues recursively (to topic T3, and so on) in a
   process called "rendering" -- performed by renderTopics(). A story
   author stores his or her topic/weight duples in the story_topics_chosen
   table, and at story save time, these choices are rendered into a
   (probably larger) collection of topic/weight duples that are stored in
   the story_topics_rendered table.
   (The above rule describes most of what is involved in the rendering
   process. The other rules in the algorithm are that if multiple children
   of differing weights both propagate up to the same parent, the greater
   of those weights become the parent's; and that any topic's chosen
   weight, including a weight of 0, always overrides any weight propagating
   up from its children.)
   Finally, when the collection of rendered topic/weight duples has been
   fully formed, all topics with weight 0 are dropped. Weight 0 can exist
   in chosen topics, but never in rendered topics.

A SIMPLE EXAMPLE

   That may sound a bit complicated, so here's a description using the
   default topics and topic_parents included with the default "slashcode"
   theme:
   tid 1: mainpage (also a nexus)
   tid 3: opensource (also a nexus)
   tid 4: slash
   tid 7: linux
   Tid 4 has tid 3 as a parent, with that relationship having a min_weight
   of 10 associated with it.
   Tid 7 also have tid 3 as a parent, with min_weight 10.
   Tid 3 has tid 1 as a parent, with min_weight 30.
   The skin at "http://example.com/" reads the nexus tid 1; the skin at
   "http://opensource.example.com/" reads the nexus tid 3.
   Suppose an editor is working on a story about Slash and assigns it the
   topic "slash," tid 4, with weight 10. Weight 10 is described as
   "Sectional only" in the code. When that story is saved, renderTopics
   recursively propagates the weight of its topics, or in this case its
   single topic, up to parents, or in this case parent. Rendering adds tid
   3, also at weight 10. It does not add tid 1 since !(10 >= 30). The story
   thus will appear only on "http://opensource.example.com/" and not
   "http://example.com/".
   Now suppose the editor re-edits the story, adding important information
   about Linux. He or she at that point adds the Linux tid 7 with a weight
   of 30. Now when it is saved, tid 1 is added since 30 >= 30. Now the
   story will appear at both URLs.
   Now suppose the editor is instructed that this story must be removed
   from "http://opensource.example.com/", though it should stay on the main
   page "http://example.com/". In the admin.pl editor, he or she adds tid 3
   with weight 0. That by itself would remove both nexuses when the story
   saves, since the 0 would prohibit both child tids from propagating
   higher than tid 3 up to tid 1. Upon clicking Preview, the admin sees
   that "This story will not appear" (see admin.pl
   getDescForTopicsRendered()). So the admin also adds tid 1 -- any weight
   greater than 0 would do, but weight of 30 makes the most sense since the
   backend describes that as "Mainpageworthy." Once this story is saved,
   its rows in story_topics_chosen are:
           tid 1, weight 30
           tid 3, weight  0
           tid 4, weight 10
           tid 7, weight 10
   and its rows in story_topics_rendered are:
           tid 1, weight 30
           tid 4, weight 10
           tid 7, weight 10
   Note that, as far as almost all of the code is concerned, the weight
   value in story_topics_rendered is irrelevant; only whether a row exists
   or not is noted. (This is why weight of 0 never appears in that table.)

DISPLAY OPTIONS AND WEIGHTS

   So how are these values of weights 10 and 30 decided, and what are 20
   and 50 for?
   Previously in Slash, there were three possible values for a story's
   displaystatus: Never Display, Section-Only, and Always Display.
   Section-Only meant to only display a story in its section's homepage,
   not the site's main page, and Always Display meant to display a story
   both places.
   Now that a story may be part of more than one skin (the new term for
   "section"), that distinction is not so simple. While the method
   _displaystatus() will return an old-style displaystatus value for a
   story, this is for reverse compatibility and is deprecated. The proper
   question now takes two arguments instead of one: is a story to be
   displayed _in_ a particular skin.
   The answer to that question is very simple; if a row exists in
   story_topics_rendered with the story's stoid and the topic's tid, then
   yes; otherwise, no.
   To prevent everything from breaking at once, and to keep the backend
   story list looking much the same as it did before (white background for
   Always Display, light gray for Section-Only, dark gray for Never
   Display), the "mainpage skin" was created. Defined by the var
   mainpage_skid [sic, a skid is a skin's numeric primary key], this
   defines which skin a story must be in to be considered "Always Display."
   It also defines which topic nexus will be colored blue instead of yellow
   in admin.pl?op=topictree (you will need GraphViz installed to see this;
   see plugins/Admin/README). Nevertheless, Slash is now well-equipped to
   run a website which consists of many subsites, at different URLs,
   perhaps only loosely networked and not necessarily with one central
   "main" page.
   multiple skins and how index.pl uses stories.primaryskid
   skins.cookiedomain and the cookiedomain var
   the Topiclist
   the topic chooser
   no admin.pl interface to edit topic tree yet, but op=topictree (and
   GraphViz, see plugins/Admin/README)
   suggestions for a clean topic tree (use min_weight 10 to connect
   many/most topics to logical categorizations, which could/should be
   nexuses, then connect those to mainpage with min_weight 30, finally
   bring loose topics to mainpage with min_weight 30)
   utils/convertDBto200406
   and _suggest and how it can be used to advise on a better topic tree
   and _render which needs to be run