As discussed at the Vancouver docs meeting, a fairly quick change that we could make to the Book Page node type would be to make an input filter that would allow for what's called in the technical communication world "conditional text".

The idea is that when you're writing a doc page that pertains to multiple versions of Drupal, for instance, you could mark some sections as relevant to Drupal 6, and others as relevant to Drupal 7, while the bulk of the page would be relevant to both D6 and D7. That way, we could avoid having to have two completely different versions of a page on d.o, when they only need to differ by a little bit.

I've filed this issue in the Doc project for now, so we can discuss the specs for what we want built. When specified, we'll need to move it to the d.o infrastructure queue so we can make an input filter that implements the spec.

The idea proposed (not fully spec'ed out yet) was something like this:
a) Have a "shortcode" that we could put into a book node, maybe:
[conditional: Drupal 6.x] (conditional d6 text goes here) [/conditional]

b) The input filter would translate this into a heading and a div, something like:

<h4 class="conditional-header">Drupal 6.x only</h4>
<div class="conditional"> (conditional text goes here</div>

c) There would be some CSS that would format this appropriately, probably highlighting the conditional code and maybe indenting it.

Once this is done, we would want to start a meta-project of consolidating our doc pages using conditional text.... but that's for later.

Comments

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Priority: Normal » Major

I'm upping priority on the highest-priority issues for docs team infrastructure.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Here's a slight variation on the above, as a concrete proposal:

a) In the text editor, you tag conditional content as follows:

Here's the all-version content. blah blah blah.
[conditional Drupal 6.x]
Specific Drupal 6 navigation or directions.
[/conditional]
[conditional Drupal 7.x]
Specific Drupal 7 navigation or directions.
[/conditional]
etc.

The author can put anything they want after "conditional" in the tag.

b) We would define an input filter that would find these conditional sections and display them as collapsed fieldsets on the page, using the text after "conditional" as the link title to open/close the fieldset. ... I was going to put a mockup here, but I can't seem to get fieldsets to work right in an issue comment. Hopefully we all understand what fieldsets look like. :)

I think I could write this module in a couple of hours at the most, and deploy it on my development d.o snapshot so we could try it out. Would that be sufficient to meet our needs, at least for now?

arianek’s picture

arianek CreditAttribution: arianek commented
Component: Other documentation issues » Docs Infrastructure
wizonesolutions’s picture

wizonesolutions
he/him
Primary language English
Location Norway
CreditAttribution: wizonesolutions commented
Component: Docs Infrastructure » Correction/Clarification

I ran across this contrib module. Is it a feasible solution?

http://drupal.org/project/collapse_text

It has a title option as well, so it seems like the use case above could be satisfied.

wizonesolutions’s picture

wizonesolutions
he/him
Primary language English
Location Norway
CreditAttribution: wizonesolutions commented
Component: Correction/Clarification » Docs infrastructure

Sorry, I borked the component somehow. Fixing.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

I'll check that out -- thanks!

Incidentally, we also probably need this for the new proposed help system for Drupal 8. See
http://drupal.org/node/1095012
I've added this contrib module to that page. I don't think it does everything we need for core help, but it is probably at least a good starting point. What I'd like to do is make a module that would work both for d.o and for the core help needs as outlined on that page.

wizonesolutions’s picture

wizonesolutions
he/him
Primary language English
Location Norway
CreditAttribution: wizonesolutions commented

jhodgdon: I've got stagingvm access. Would you like help? We could use the module to at least prototype the functionality for the docs team on the current site since it's already put together - then improve or redo it as needed. Plus, I can get my feet wet working on d.o infra.

wizonesolutions’s picture

wizonesolutions
he/him
Primary language English
Location Norway
CreditAttribution: wizonesolutions commented

Ah, and that's right - if you do want help...which staging site should I use?

lisarex’s picture

lisarex CreditAttribution: lisarex commented

Subscribe

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

I have a staging site too, so that is not a problem.

There is an updated proposal for a D8 help system that includes conditional text ability, with more functionality than shown here, at:
http://drupal.org/node/1095012

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Issue tags: +valid issue

Tagging so it doesn't get picked up by #1421874: [meta] Documentation Issue Queue Cleanup

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Issue tags: -drupal.org documentation tools

removing unneeded tag

LeeHunter’s picture

LeeHunter CreditAttribution: LeeHunter commented
Issue tags: +Usability