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?):

• woes-conditional-text

• When Conditional Content Goes Wild: 4 Top Tips for Avoiding Pain – Part 1
• When Conditional Content Goes Wild – Part 2: Securing Support and Making Deep Changes

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.