The content of this blog is my personal opinion only. Although I am an employee - currently of Nvidia, in the past of other companies such as Iagination Technologies, MIPS, Intellectual Ventures, Intel, AMD, Motorola, and Gould - I reveal this only so that the reader may account for any possible bias I may have towards my employer's products. The statements I make here in no way represent my employer's position, nor am I authorized to speak on behalf of my employer. In fact, this posting may not even represent my personal opinion, since occasionally I play devil's advocate.

See http://docs.google.com/View?id=dcxddbtr_23cg5thdfj for photo credits.

Friday, December 05, 2014

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.


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

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.


Andy "Krazy" Glew said...
This comment has been removed by the author.
Andy "Krazy" Glew said...

I suspect that better tools to manage aspects in techwriting, better tools to manage conditional text and transclusion, may help techwriting as much as aspect oriented programming has helped programming.

(Actually, AOSP I think still has much left to do. But nevertheless it has helped.)

The tools may in fact be the same: Literate Programming for ... Technical Literature... ?

Andy "Krazy" Glew said...

Or, rather: some AOSP tools, such as many of those I have written, amount to disentangling and reweaving text. The programming parts comes in when you transform the text to do some programming task - automatically generate a method, help (perldoc is AOSP). Techwriting may do less transformation, but still there is some.

Andy "Krazy" Glew said...

First, an observation: conditional text may be a pain anywhere, but I think that conditional text is easier handle in text based markup languages like TeX than it is in WYSIWYG like Word or FrameMaker. (Have I mentioned today how much I hate FrameMaker? Especially binary FrameMaker, with a techpubs group that does not believe in automation.?)

I think the reason is that in a text-based markup language, you can create fairly arbitrary conditions: "print this if 64-bit or 32-bit and >32-bit virtual addresses".

Whereas, even if your WYSIWYG editor supports arbitrary conditions (FrameMaker did not, for the longest time), it is hard to depict the combinations of such conditions in a WYSIWYG manner. Inspiring this post.