SectionTopics
Jump to navigation
Jump to search
CssWork parent
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