expose new toc features in the document toc element

[Andy Altepeter]

The new toc features (e.g. showing more meta types, sorting options) need to be exposed to the toc element in kupu and the forms-based editor.

[Andy Altepeter (aaltepet)]

Should the table of contents element be converted into an external source? That would clean up the toolboxes a bit, although content with tocs would need to be upgraded. Kit, I think you've hinted in the past that these custom elements should eventually be converted into ES's. At this point, the only advantage to an autotoc tool is that it is slightly easier to use, being always present as a toolbox. But, converting to an ES would cleanup the kupu codebase, and would arguably be less work to implement. if this is a direction you want to head, I would recommend adding it as a core filesystem-based external source in the SilvaExternalSources product.

Otherwise, I can implement the autotoc features in kupu and the 'toc' edit widget.

[Andy Altepeter (aaltepet)]

Also, there is already a MultiTOC external source, so this could be merged with the new features of toc in a new TOC external source.

[Kit Blake (kitblake)]

Excellent point, yes, I think it's time to start converting these custom elements (TOC and Citation) to CodeSources. We'll have to work out the deprecation strategy. Maybe first supply the CS, make the TOC not available anymore, but still render existing ones with a message about conversion.

This should hook into the long term objective where we have an upgrade that transforms Silva XML into a clean subset of XHTML. We want to keep upgrades of content to a minimum because they're painful for sysadmins. Any thoughts?

[Andy Altepeter (aaltepet)]

I've created a TOC code source and placed it in the code source service in the SilvaExternalSources trunk

This CS is a merge of the features in the multitoc source and those in the AutoTOC content type. This is being created with the intent of replacing the toc document element. With similar features to the multitic, I think it also has the potential of replacing multitoc, so Silva has a single official TOC element -- simpler from a user perspective, and certainly simpler to maintain.

So, please evaluate and provide feedback, especially on where you want me to go next with this.

 The HISTORY.txt in the code source needs to be updated, and likely other consistency issues with the documentation of this source as well.

[Kit Blake (kitblake)]

Andy, the one thing that comes immediately to mind is we'll need an upgrader, at some point, to transform existing TOCs (inline or AutoTOCs) into the new code source. But maybe it's better to wait until the code source finalizes. Could be that fields change name or such.

I don't think we need any "code source to code source" transformers. There just aren't that many Multi-TOCs out there. Or if I'm wrong that should become a project.

[Andy Altepeter (aaltepet)]

Kit, since you assigned Todd to this, I subscribed you to make sure you see this post.

I've created an upgrader for Silva 2.2 which converts toc elements in Silva XML to cs_toc code sources. It'll be easy to change the upgrader if the cs parameters change, so I'm not concerned about that. Do you want the upgrader in 2.2? Mandatory? Or, provide instructions on how to manually run using partial upgrades?

What do you want to do about the toc element in kupu? Display a warning about it being deprecated, not allow adding new ones, but allow editing existing ones? Or did you want to display a warning, and allow adding new / editing existing? Or, assume the upgrader was run, and remove the toc element altogether?

And then the forms-based editor. I know it's possible to remove an element from the add list, so I can configure that. And then, like what was done with the 'code' element that changed into 'source', just leave the edit and view/preview widgets registered. After an arbitrary number of releases, these widgets can be removed from the codebase.

How are you wanting to convert AutoTOC's, and what are you wanting to convert them to?

[Andy Altepeter (aaltepet)]

oh, one more question. Currently, the upgrader converts _all_ document versions. Should it do that? Or, should it only convert the published and unpublished versions, leaving the closed versions untouched (as "history")?

Also (more a note for myself, and to put in whatever developer notes we write about this) : can an upgrader be registered on a base class or interface? If not, this upgrader will need to be registered for all known versionedcontent objects which use silvaxml, e.g. SilvaDocument, Silva News Item, Silva Agenda Item, ??

[Andy Altepeter (aaltepet)]

1) I registered the upgrader for the special AnyMetaType object, so it's called for all objects
2) it is no longer possible to add tocs via either the forms-based editor or kupu
3) the upgrader converts all versions
4) on install/refresh the "cs_toc" is copied to the root, if it isn't already there
5) the kupu toc element displays a note regarding the deprecation of this tool.

I still need to add documentation regarding this major change.

[Andy Altepeter (aaltepet)]

added a note to developer_notes.txt.

Todd, could you add functional tests for cs_toc?

Since cs_toc superceded cs_multitoc, I've removed cs_multitoc from the codesources directory of SES. This may have broken the SES func tests, too.

[Kit Blake (kitblake)]

All the 1-5 above sound fine. Thanks.

About the AutoTOC, probably we should leave it as it is, unless people think we should toss the content type, and insert a normal index with a cs_toc. But it's so convenient to add an AutoTOC.

We'll have to do something similar with the citation element. I'll make an issue about that.

[Kit Blake (kitblake)]

Andy, where's the note in developer_changes.txt? Maybe I'm not svn upped properly.

[todd (todd-infrae)]

Andy Altepeter wrote:
> added a note to developer_notes.txt.
>
> Todd, could you add functional tests for cs_toc?
>
> Since cs_toc superceded cs_multitoc, I've removed cs_multitoc from the
> codesources directory of SES. This may have broken the SES func tests,
> too.
>
>
Yeah,

I'm not sure SES had func tests but this would be a good place to start
them.

Cheers,

T

[todd (todd-infrae)]

Andy Altepeter wrote:
> added a note to developer_notes.txt.
>
> Todd, could you add functional tests for cs_toc?
>
> Since cs_toc superceded cs_multitoc, I've removed cs_multitoc from the
> codesources directory of SES. This may have broken the SES func tests,
> too.
>
>
Andy there is a functional test, but no unittests. I took out the
cs_multitoc from configure and the func test, replacing it with toc.

T

[Andy Altepeter (aaltepet)]

I added a note to developer_changes.txt and UPGRADE.txt

[Andy Altepeter (aaltepet)]

released in 2.2alpha