One big problem for WYSIWYG conditional text is allwing the editor to recognize the conditions.
Basically, to do WYSIWYG editing of conditional text, you need to be non-WYSIWYG ... :-(
There are only a few things that you can do to distinguish different conditions:
* use color
* use font bold, italic. Fontsize not so good.
* use background colors
* use marks like underlining, strikethrough, crosshatching.
Anything that is used to indicate conditions might conflict with the same visual effects used in the final document. Not so bad if preparing for publication in the traditional press, which is largely black and white. Bad if you want to use those effects, e.g. on a webpage.
If you have limited colors, say 4, and limited effects, say single and double underling => well, you only get 8 combinations. But even the v123 tABC example exceeds that.
You get to 4x4x4x2 if you allow all combinations of letter color, underline color. and background color. I don't know of a tool that does this. Sure, it would look cluttered - but I suspect that my brain coukld decode.
Of course, have more colors than 4. But conversely, probably don't use exactly the same colors - foreground text red on background red is useless. The system probably needs to automaically adjust, so that it is foreground red on a immd red that can show the contrast. Conventions.
---
Not to mention that we want to see overlapping tags. E.g. reserve background color for one set of tags, v123; text for another tABC. This doesn't scale.
---
Two effects may scale:
underlining with different colors
flyovers - these can indicate arbitrary combos of conditions.
---
Part of the trouble in managing WYSIWYG conditional text is that an upstream usr may decide to user a color that you have already used.
Quite apart from the logic.
Friday, December 05, 2014
Logic for conditional text
Before I talk more about WYSIWYG for conditional text, an observation: tagging, labelling text.
For many years FrameMaker only allowed ORing of conditional text tags: if a piece of text was tagged with both A and B, it would pint if either A or B was true. There was no way of saying that both A or B had to be true.
Sure, FrameMaker eventually fixed that. First ANDing. AND NOT. Then parenthesizes. I am not sure if it is arbitrarily complex yet, but it is better than it was. (I wish my company used that version of FrameMaker, or did not use FrameMaker at all.)
In theory all conditions could be expressed by sum of product minterms or product of sum maxterms, with NOT. Hck, it could all be expressed by NAND and NOR. But that would be a pain.
Part of the problem is that conditional text tagging is done at different times, by different people - or, worse, simultaneously by people who are not necessarily coordinating. And that the logical expressions required are fragile - one contributor adding a tag may "EXPLODE" the logical expressions needed to handle his text, when transcluded by somebody else. Fragile base class all over again!
Say that user1 is producing three versions of a document, tagged V1, V2, V3. Just those tags are used- no "not-V1". The logic to determine if text is displayed is not "V1 or V2 or V3" - it is actually "Untagged OR V1 OR V2 OR V3". If text is tagged both V1 and V2, it displays if either V1 or V2 is being produced, but not V3.
(Much confusion occurs because people forget the implicit "Untagged". Assuming "Untagged => "display in all versions".)
But user2 has added a different set of tags: let's say TA, TB, TC. Same logic: "Untagged OR TA OR TB OR TC".
I am deliberately not using binary tags, X and not-X. I have observed that often tags come in these mutual-??? sets. Not really mutually exclusive - text may be tagged both V1 and V2. But the V1 and V2 versions are conceptually separate. The problem, of course, arises because I often like to create a readable mta-document, a unified version, rather than having to cope with combinatoric explosion. But that's for later.
Now the user1 and user2 conditions may combine. Combinatoric explosion.
Emphasizing: it is NOT user1.condition OR user2.condition: NOT "Untagged OR V1 OR V2 OR V3" OR "Untagged OR TA OR TB OR TC" => "Untagged OR V1 OR V2 OR V3 OR TA OR TB OR TC".
E.g. we may be generating the combination V1.TB => "(Untagged OR V1) AND (Untagged OR TA)"
Where people get into trouble is when they try to implement this via a UI (User Interface) which is supposedly simpl, and indicates whether tag is wanted or not via V1wanted=0 or V1wanted=1. Part of the trouble is that, at the very least, you need 3 stats for a wanted predicate: definitely wanted, definitely not wanted, and "I don't care".
As in "I want all text related to V1".
I don't want any text related to V2 (unless it happens to also be tagged related to V1".
And "I don't care if the text tagged V2 is included or not".
In all cases the text is conceptually passed on to another layer, with the tags intact; and only at the end are all conditions stripped out.
E.g. V[123].T[ABC] => V[12].T[BC] => T[1].T[B].
Worse, the ultimate user may not know of options or tags added by a user earlier in this pipeline. From the ultimate user's point of view, he may know that he dies not want any TC stuff, but he dos not know if user2 has added a TD alternative. So the downstream user cannot say TA|TB|TD - he just says "Not TC". Which is only meaningful in the context of a mutual group T[ABCD], whre "not TC" really means "Untaged OR TA OR TB OR TC" or "Untagged or Any Tag in the T* group except TB".
E.g. a microprocessor family that evolved through 8. 16, 32, and 64 bit versions, like x86 (not to mention 20 and 24 bit stags).
Let's say a user wants just the 8 and 16 bit versions. If he says "not 32", then he gets 64. Would that not be strange - having documentation for the 8 16 and 64 bit versions of a CPU, but not the 32? (Although I can imagine...)
So saying "not 32" normally also implies "not 64". Or, perhaps "not 32" really means "wordsize < 32" or "wordsize NOT >= 32".
But user1 may introduce a different tag that is not part of this evolutionary sequence - so not-32 should not imply not-virtual-machine.
The problem is that a condition that works at one time may not work going forward, as more tags are added.
For many years FrameMaker only allowed ORing of conditional text tags: if a piece of text was tagged with both A and B, it would pint if either A or B was true. There was no way of saying that both A or B had to be true.
Sure, FrameMaker eventually fixed that. First ANDing. AND NOT. Then parenthesizes. I am not sure if it is arbitrarily complex yet, but it is better than it was. (I wish my company used that version of FrameMaker, or did not use FrameMaker at all.)
In theory all conditions could be expressed by sum of product minterms or product of sum maxterms, with NOT. Hck, it could all be expressed by NAND and NOR. But that would be a pain.
Part of the problem is that conditional text tagging is done at different times, by different people - or, worse, simultaneously by people who are not necessarily coordinating. And that the logical expressions required are fragile - one contributor adding a tag may "EXPLODE" the logical expressions needed to handle his text, when transcluded by somebody else. Fragile base class all over again!
Say that user1 is producing three versions of a document, tagged V1, V2, V3. Just those tags are used- no "not-V1". The logic to determine if text is displayed is not "V1 or V2 or V3" - it is actually "Untagged OR V1 OR V2 OR V3". If text is tagged both V1 and V2, it displays if either V1 or V2 is being produced, but not V3.
(Much confusion occurs because people forget the implicit "Untagged". Assuming "Untagged => "display in all versions".)
But user2 has added a different set of tags: let's say TA, TB, TC. Same logic: "Untagged OR TA OR TB OR TC".
I am deliberately not using binary tags, X and not-X. I have observed that often tags come in these mutual-??? sets. Not really mutually exclusive - text may be tagged both V1 and V2. But the V1 and V2 versions are conceptually separate. The problem, of course, arises because I often like to create a readable mta-document, a unified version, rather than having to cope with combinatoric explosion. But that's for later.
Now the user1 and user2 conditions may combine. Combinatoric explosion.
Emphasizing: it is NOT user1.condition OR user2.condition: NOT "Untagged OR V1 OR V2 OR V3" OR "Untagged OR TA OR TB OR TC" => "Untagged OR V1 OR V2 OR V3 OR TA OR TB OR TC".
E.g. we may be generating the combination V1.TB => "(Untagged OR V1) AND (Untagged OR TA)"
Where people get into trouble is when they try to implement this via a UI (User Interface) which is supposedly simpl, and indicates whether tag is wanted or not via V1wanted=0 or V1wanted=1. Part of the trouble is that, at the very least, you need 3 stats for a wanted predicate: definitely wanted, definitely not wanted, and "I don't care".
As in "I want all text related to V1".
I don't want any text related to V2 (unless it happens to also be tagged related to V1".
And "I don't care if the text tagged V2 is included or not".
In all cases the text is conceptually passed on to another layer, with the tags intact; and only at the end are all conditions stripped out.
E.g. V[123].T[ABC] => V[12].T[BC] => T[1].T[B].
Worse, the ultimate user may not know of options or tags added by a user earlier in this pipeline. From the ultimate user's point of view, he may know that he dies not want any TC stuff, but he dos not know if user2 has added a TD alternative. So the downstream user cannot say TA|TB|TD - he just says "Not TC". Which is only meaningful in the context of a mutual group T[ABCD], whre "not TC" really means "Untaged OR TA OR TB OR TC" or "Untagged or Any Tag in the T* group except TB".
E.g. a microprocessor family that evolved through 8. 16, 32, and 64 bit versions, like x86 (not to mention 20 and 24 bit stags).
Let's say a user wants just the 8 and 16 bit versions. If he says "not 32", then he gets 64. Would that not be strange - having documentation for the 8 16 and 64 bit versions of a CPU, but not the 32? (Although I can imagine...)
So saying "not 32" normally also implies "not 64". Or, perhaps "not 32" really means "wordsize < 32" or "wordsize NOT >= 32".
But user1 may introduce a different tag that is not part of this evolutionary sequence - so not-32 should not imply not-virtual-machine.
The problem is that a condition that works at one time may not work going forward, as more tags are added.
Aspects, Conditional Text, and WYSIWYG
I like "aspect oriented programming".
In my undergrad, well before I had heard of AOSP, I was writing tools so that I could manage all of the aspects of an instruction definition in a single place - and then distribute them to multiple places.
E.g.
instruction name: OR
encoding: 00000.rd5.rs5.imm16
action: GPR[rd] := GPR[rs] + imm16
traps: none
latency: 1
instruction name: FADD
encoding: 00000.fd5.fsrcA5.fsrcB5.imm16
action: FPR[fd] := FPR[fsrcA] + FPR[fsrcB]
traps: FP-traps
latency: 4
I would then split up this stuff to generate many different files used in CPU toolchain: simulator decoder, execution, disassembler, compiler timing tables, etc. Combining with other specs - e.g pipeline (latency might be defined there instead), etc.
(I also used to generate the opcodes to minimize logic, but that's a different story.)
But this invoves looking at the aspects sorted according to only one criteria, in this case by instruction. Sometimes you waant to sort by other criteria: the sort key is itself an aspect
E.g. sorted by property
instruction name: OR
instruction name: FADD
traps: OR: none
traps: FADD: FP-traps
encoding: FADD: 00000.rd5.rs5.imm16
encoding: FADD: 00000.fd5.fsrcA5.fsrcB5.imm16
action: OR: GPR[rd] := GPR[rs] + imm16
action: FADD: FPR[fd] := FPR[fsrcA] + FPR[fsrcB]
latency: OR: 1
latency: OR: 4
would like to be able to edit in any rearrangement of the aspects, and still have it generate.
Database views: some editable, some read only.
Later, realized that, even though might not be able to edit and regenerate some views, often can verify consistency of non-generatable view.
---
In techwriting, conditional text is the most primitive support for AOSP - AOTW? But conditional text can be hard to deal with. I would not be surprised if there was a polemic CONDITIONAL TEXT CONSIDERED HARMFUL. Heck, in programming, I wrote a diatribe IFDEF CONSIDERED HARMFUL, very much the same. And a friend has said that he would like to have a simulator with no IF statements... (not exactly that).
Ah, here are some TW equivalents of Dijkstra (why is it that techwriters do not write as well as Dijkstra the computer scientist?):
I have made a minor step forward in this area by realizing that one of the good things from programming - writing tests that should apply to all implementations of an interface - also applies to documentation. Many aspects (coincidence?) of documentation can be automatically tested. Such automated tests for documentation help maintain invariants and standards both when there is lots of conditional text and transclusion, and when there has been lots of replication via cut and paste.
--
But what I want to talk about is making conditional text (and transclusion) easier to manage.
In my undergrad, well before I had heard of AOSP, I was writing tools so that I could manage all of the aspects of an instruction definition in a single place - and then distribute them to multiple places.
E.g.
instruction name: OR
encoding: 00000.rd5.rs5.imm16
action: GPR[rd] := GPR[rs] + imm16
traps: none
latency: 1
instruction name: FADD
encoding: 00000.fd5.fsrcA5.fsrcB5.imm16
action: FPR[fd] := FPR[fsrcA] + FPR[fsrcB]
traps: FP-traps
latency: 4
I would then split up this stuff to generate many different files used in CPU toolchain: simulator decoder, execution, disassembler, compiler timing tables, etc. Combining with other specs - e.g pipeline (latency might be defined there instead), etc.
(I also used to generate the opcodes to minimize logic, but that's a different story.)
But this invoves looking at the aspects sorted according to only one criteria, in this case by instruction. Sometimes you waant to sort by other criteria: the sort key is itself an aspect
E.g. sorted by property
instruction name: OR
instruction name: FADD
traps: OR: none
traps: FADD: FP-traps
encoding: FADD: 00000.rd5.rs5.imm16
encoding: FADD: 00000.fd5.fsrcA5.fsrcB5.imm16
action: OR: GPR[rd] := GPR[rs] + imm16
action: FADD: FPR[fd] := FPR[fsrcA] + FPR[fsrcB]
latency: OR: 1
latency: OR: 4
Database views: some editable, some read only.
Later, realized that, even though might not be able to edit and regenerate some views, often can verify consistency of non-generatable view.
---
In techwriting, conditional text is the most primitive support for AOSP - AOTW? But conditional text can be hard to deal with. I would not be surprised if there was a polemic CONDITIONAL TEXT CONSIDERED HARMFUL. Heck, in programming, I wrote a diatribe IFDEF CONSIDERED HARMFUL, very much the same. And a friend has said that he would like to have a simulator with no IF statements... (not exactly that).
Ah, here are some TW equivalents of Dijkstra (why is it that techwriters do not write as well as Dijkstra the computer scientist?):
Similarly wrt transclusion. From woes-conditional-text:
When you have just a few conditions or transclusions with your content, there’s no problem. But when you suddenly realize that editing the topic is requiring an immense amount of concentration and careful analysis because you’ve got too many conditions or transclusions to sort out in your mind, you have to consider whether simply copying and pasting is more efficient.This is very much like the Fragile Base Class Problem in programming - and many object oriented gurus recommend "reuse interface, not implementation".
I have made a minor step forward in this area by realizing that one of the good things from programming - writing tests that should apply to all implementations of an interface - also applies to documentation. Many aspects (coincidence?) of documentation can be automatically tested. Such automated tests for documentation help maintain invariants and standards both when there is lots of conditional text and transclusion, and when there has been lots of replication via cut and paste.
--
But what I want to talk about is making conditional text (and transclusion) easier to manage.
Subscribe to:
Posts (Atom)