Starting Your Story

Posted on 2022-08-08 by Stephan Sokolow

For over a decade now, no thanks to various set-backs, I’ve been taking notes for a book on how to write fiction (and planning a tool for organizing them).

You might ask why, when there are already so many other books like that. Well, three reasons:

  1. Many of them are either about the spiritual/lifestyle experience of writing or the business of getting published or about a very narrow field of information, like how to write horses. None of those are very helpful for who I was in high school, when I started this whole idea.
  2. Books about writing tend to fall into two categories:
    1. Books by academics, who have deep understanding, but are so focused on literary theory as it applies to analysis and criticism that it’s hard to make the leap to apply their insight to creating new works.
    2. Books by published authors who take some part of their insight for granted when it’s actually part of the reason they became skilled authtors while I needed to start this whole project. (The best teacher is one whose understanding didn’t come easily.)
  3. Those books cost money. My goal is to increase the quality and quantity of stuff out there for me to read. That means trying to help amateur/hobbyist authors improve. It’s already going to be hard enough to convince them to spend time reading my book without charging for it… especially for fanfiction authors.

So, with that said, here’s the first draft of a fragment which I don’t think needs to wait for the full book. The final version will be edited heavily to make it clearer, punchier, and less reliant on advanced vocabulary which might drive away teenage fanfiction authors, but it’s good enough for now.

Feel free to debate the correctness of any of this in the comments. If there’s something I got wrong, I want to know. If I can prove I’m right but you’re not convinced, I still want to know. It’s a draft for a reason.

That said, let’s get started.

Laying Out Your Concept

There’s a set of questions I like to ask whenever I’m preparing to write or mothball an idea, or helping a friend with one of theirs. They’re the kind of simple things that can take less than a minute if you already know what you want, but are very important to ask yourself if you don’t.

There will be no “fill out this character sheet that’s half irrelevant to your story” here. Just a few simple questions you can ask and answer… though you might still want some paper. Writing, typing out, dictating, or explaining your ideas to someone else forces your brain to think fresh thoughts instead of reusing old ones, and that helps to prevent writer’s block. (This is why you’re likely to realize the answer to a problem in the middle of asking someone else for help.)

Yes, this is a long post, but only so you understand why these questions are important and what kind of answers you should be looking for.

What’s The Raw Idea?

This one is a bit of an exception, because, unlike the others, the answer does need to be written down, but the question only needs to be asked in certain situations.

Before you do any brainstorming, it’s important to write down your idea in the purest form possible. Brainstorming or, sometimes, even trying to put an idea into words, can lead you astray and it’s important to have a solid record of that initial spark of inspiration so you can back up, refresh your memory, and try a different path if you find that the “magic” is fading.

Often, your earliest inspiration will be hazy, and mostly a feeling, so this takes a surprising amount of practice to do reliably. I’ve actually lost a couple of ideas because the emotional spark that made them special slipped through my fingers while I was trying to put them into words, but you get better with practice.

I recommend doing this in at least two stages:

First, write down the purest, rawest description possible. Don’t try to be coherent. Don’t try to make sense. Don’t try to figure out how it would work as a story… just write the first words that come to mind to describe what you’re thinking and feeling. Don’t risk losing it by thinking it through. You’re trying to make a backup of your emotional state.

Second, now that you’ve got a safety net, start writing out a more coherent version, and allow yourself to think about what will and won’t work. Do this several times if you need to… just draw out as much of the idea into written form as you can so you have a solid basis for the questions that don’t need to be written down.

Don’t be afraid to do this in as many stages as you need. You’re trying to make a backup of a spark of inspiration, not how you think it needs to be implemented, and the big hazard is dismissing something as “that’ll never work” without even noticing what you did. A good story is just as much about the emotional experience as the rational, and good writing is about thinking out of the box, so you need to know what felt so special so you can keep looking for less obvious ways to polish up and purify that experience.

What’s The Driving Conflict?

If you don’t remember high school English class, every novel, every novella, and many short stories are built around a driving conflict. The arc of the story starts with a character who was used to their situation, then something happens that shakes them out of that normalcy, and the story follows them as they do something to resolve that discomfort. In other words, a conflict can be anything that drives the character to push back and seek to change things.

People are most familiar with conflicts like “Voldemort is trying to steal the Philosopher’s Stone” or “Lex Luthor stole 40 cakes (and Superman needs to get them back)” but things like “The main character is struggling with depression” also work to motivate a story. It needs to be something where there can be a sense of resolution at the end, so the story can have an arc, but, otherwise, anything goes. Depression isn’t going to go away overnight, but seeing the light in the distance can be a triumph. What’s important is having a a problem with a resolution that motivates the main character to get up and do something, so the story can start when it begins and end when it’s resolved.

Stories don’t technically need a driving conflict (they just need to be interesting and to change enough to avoid getting stale), but our cultural upbringing trains us to expect one so strongly that, if you don’t have one, readers will cloud-watch their way to what they think the conflict is, and then be unsatisfied when you break that expectation.

In the end, it’s best to think of a driving conflict as a guide for the author, like a compass. It keeps you pointed in the right direction to make your storytelling as powerful as possible. It also lets you know when you’ve arrived and it’s time to end one volume and begin the next. (But don’t be like Diana Wynne Jones with Dark Lord of Derkholm and Year of the Griffin and forget necessary epilogues. Readers need to feel the protagonist’s success or the story will feel incomplete and, sometimes, it takes long enough from when they’ve won to when they see the results that you need that time-skip.)

One example of a driving conflict is “Character finds themself uprooted and moved to a new neighbourhood. They have to make new friends and generally find a new comfort zone in this new environment.” (And, if that sounds boring, think about this: It’s the basis for many “stranger in a strange land” stories in science fiction and fantasy. Context matters.)

You want to introduce the conflict as early as possible, because readers and editors expect you to hook them by the end of Chapter 1. That means making a first impression that accurately represents what the rest of the story will feel like.

(Authors who take their insight for granted sometimes call this “start right into the action”, not realizing that novice authors can have a very narrow definition of “action” which can ruin what would have become deep and nuanced but non-martial conflict.)

You can have a time-skip before the point where you need to have your readers hooked though. “By the end of Chapter 1” makes allowances for having a prologue or two as long as they’re not too long. (At the same time, if your “Chapter 1” is 20,000 words long, readers may just refuse to give it a chance in the first place.)

That said, you can write a story about anything, so let’s introduce an example conflict I can build on.

Suppose you want to write a story about getting a bite to eat and then getting back to a game you’re playing.

Before the story, you’re sitting in a chair, playing a game. That’s your introduction. Then, you feel hungry. That’s the conflict. You go to the kitchen and get some food. That resolves the conflict. Then, the epilogue shows how satisfied you are from actually eating the food. (Note how the conflict is resolved as soon as success is assured, and then it time-skips to the epilogue. Showing the busywork between those two points just dilutes the story but the epilogue is necessary for the satisfaction.)

What Is Your Chosen Resolution?

Once you’ve got your conflict, think about how you plan to resolve it. You don’t need a lot of detail, and there will probably be only a few possibilities and they’ll probably be obvious.

For example, if a hero is going after a villain, the hero can defeat them, the hero can fail tragically, the villain can escape to menace another day, there could be a twist that leads to the villain being redeemed, etc.

This is important for two reasons. First, it helps to reinforce the use of the driving conflict as a compass for finding your way. Second, it may reveal a problem.

If you know how your story is going to start, and you know how your story is going to end, but the conflict at the start doesn’t match the resolution at the end, then you’ve got a series on your hands, and you need to disentangle the two conflicts.

(The purpose of breaking your story into volumes is to choose where the reader will take a rest, to avoid the risk of them not resting and burning out if your story is very engaging, and to refresh their memory of details that will be important later. Professional editors require first-time authors to keep their submissions between 80,000 and 120,000 words so they have enough length to easily explore the idea in proper depth but not so much that they wear out the reader. )

Aside: Story Conflicts and Series Conflicts

When thinking about your conflict, it’s also important to understand that conflicts come in more than one type. In fact, you’re likely to see three (really more like two and a half) different kinds of conflicts in a series of novels:

First, is what I’ll call the “story” or “acute” conflict. These are conflicts where things happen quickly, and tension can be like a roller-coaster. An example would be in the first Harry Potter book, when someone is trying to steal the Philosopher’s Stone. You always need at least one of these, and they seem important, but they’re actually the weaker of the two major kinds.

Acute conflicts break down into the driving conflict for the story as a whole, which I already mentioned, and any conflicts that drive subplots, which is why I said there are two and a half kinds. However, they’re not really fundamentally different… you just use them differently.

(Subplots deserve their own post but the basic idea is that, since any realistic conflict will ebb and flow, it’s useful to have other things going on, which you can cut away to when a lull in one conflict shouldn’t cause a lull in the story and time-skipping wouldn’t give events a chance to sink in properly. You basically think about them the same way as the driving conflict, except you have to make sure they’re finished before or at the same time as the driving conflict.)

Second, the other kind of conflict: What I call “series” or “chronic” conflicts. These are conflicts which move slowly but powerfully. In the Harry Potter example, this is your “Voldemort is out there and it’s him or Harry.”

A series doesn’t need a series/chronic conflict (look at sitcoms), but it helps to tie it together into one big arc and allows you to build a different kind of attachment in the reader. A story/acute conflict will let you wind up the readers like a coiled spring… but the slow, steady movement of a series/chronic conflict can build a deeper connection.

However, a series conflict also moves slowly but powerfully inside the story’s universe… it defines the arc for something that can only be written as an epic… for those who weren’t in class that day, an “epic” is a story where a small, ordinary person winds up changing the world.

Thanks to Peter Jackson’s adaptation of Lord of the Rings, you probably think “throw the Ring into Mount Doom” when you think of a small, ordinary person changing the world… but fantasy is strongly wedded to stories with simplified morals and goals, so let’s look elsewhere.

It’s the 19th century or some equivalent, your lead character is a woman or a member of some other underclass, and you’ve tasked them with being the hero who defeats some aspect of systemic discrimination that exists in their society. That’s not something that can be done in a single acute conflict. Human power structures are just too wedded to preserving the status quo. (And it’s deeply rooted in human psychology, so you can’t just cheat by making your characters non-human. Either they think enough like humans that the same problem applies, or you’ll spend at least as much time and effort teaching your readers to relate to them.)

Once those in positions of power stop ignoring your hero, and then stop laughing them off as impotent, they will use their power to protect the system that has treated them so well. Individuals who are open-minded but happy with their lot in life won’t want to accept that the world is so much darker than they thought. People who have grown used to being helpless are likely to fear the uncertainty of suddenly being given so much agency. People who have been raised to see their victim-hood as normal are going to recoil from the emotions of having to accept that they were victimized. Society has inertia… and a lot of it.

Even if you acknowledge that fixing something like that is going to be a multi-generational effort, and your character’s triumph will be merely setting society on a new course, your character is going to need a long series of books to achieve that goal. The readers will burn out and lose interest if you just try to stretch out an acute conflict, but they still need to be carefully shown how your character is going to counteract all that inertia and make it stick… Step by step. Bit by agonizing bit. …or your story will feel either shallow and unbelievable, or impermanent… a won battle in a lost war. That is why series conflicts are needed.

It’s also important to recognize that the tension for a story can have different shapes. Harry Potter’s series conflict is an arc. Voldemort and the Death Eaters gain power throughout the books until the big climax, and then tension falls back… like a slower but more powerful version of an acute conflict. By contrast, something like Sherlock Holmes is a more or less flat sequence of acute conflicts. Yes, there’s the Reichenbach Falls bit with Moriarty, but it’s otherwise just a sequence of independent cases, each one revealing something new about Holmes’s character. (A topic for another post. Characters who grow vs. characters who you just keep learning new facets of. Holmes doesn’t grown and change, but your perception of him certainly does.)

So, with that said…

What Type Of Conflict Is It?

Another thing your high school English teacher probably taught you is the types of conflict, with names like “man against man” and “man against nature”.

You can write a story about anything… the only question is how you make it interesting, and this is where conflict types come in. They ask you to commit to focusing on a specific interpretation of your conflict so you can really make it powerful. (Because you will run into situations where you could focus on more than one interpretation of the conflict, and consistently building up the same one makes for a more effective story.)

That doesn’t mean you shouldn’t have multiple meanings that are relevant to the story (In fact, it’s very satisfying to the reader if something like your story’s title does reveal itself to have multiple meanings in the context of the story.), but the distinction is easier to demonstrate than to explain.

I’m going to modify the list of types a bit, because the set you see on sites like Wikipedia is good for grouping a specific set of classical fiction based on their cultural significance, but it isn’t as useful for classifying how to think about ideas you want to write into new fiction.

First, I will be using “person(s) vs. …” instead of “man against …” because you can anthropomorphize anything (see, for example, Millicent and the Wind by Robert Munsch) and inexperienced authors don’t need “man” unnecessarily biasing their thoughts toward human characters.

Second, I will be using five categories, instead of the traditional four, because, as I hope you’ll see from my descriptions, “person(s) vs. fate” is just as fundamental as person(s) vs. person(s), self, society, and nature.

So, with that out of the way, what kinds of conflicts can we use for our “quest for a snack” idea?

Person(s) vs. Person(s)

This is what everyone thinks of first when they think of conflict. One or more protagonist characters against one or more antagonist characters. Unlike person(s) vs. society this is about antagonists who get explored as individuals acting on their own agency, instead of as agents of the values of a prevailing social norm.

Pitting a hero against a villain falls into this category and is a perfect example of everything that can go right or wrong with this kind of conflict. Bad authors tend to be drawn to the most simplistic interpretation of it, while good authors recognize how much freedom villains have to explore interesting motivations. (The only thing that truly defines a villain is their decision to achieve their goals in a way that is unacceptable to the hero and the readers who see the story from the hero’s perspective. Villains can be sympathetic or misunderstood or tragic or countless other things.)

Likewise, a protagonist doesn’t have to be a hero. Reading a story where you’re rooting for someone who isn’t exactly a “good person” is what the idea of the antihero is all about.

…but person(s) vs. person(s) doesn’t have to be martial conflict. It’s just two people or groups of people who can’t agree on a way to get what they both want, so they struggle against each other. Maybe one wins. Maybe they learn to compromise… or maybe it’s a tragedy where the protagonist isn’t the only one who fails. (Unless it’s two protagonists pitted against each other where both are “the good guy”. Then, it’s probably “person(s) vs. fate”.)

For the quest for a snack, you could go the easy route and make the antagonist one or more roommates or family members… but anything can be personified in fiction. What about a naughty pet? Maybe it’s a tragedy where the protagonist tries so hard, only for their cat to sit on their keyboard and ruin their game.

…or even better. I did say anything can be personified. Maybe your character needs some kind of assistive device which is overdue for replacement and seems to glitch out at just the wrong times in just the wrong ways, like the malfunctioning machinery that torments Donald Duck in classic Disney shorts like Tugboat Mickey and Clock Cleaners. Heck, if you’re creative enough, you could write a gripping short about a guy and his obstinate bottle opener. Go wild!

Person(s) vs. Self

Person(s) vs. self is about the protagonist being their own enemy.

Note that this doesn’t apply to stories about people with split personalities if the personalities are treated as separate characters. This is about a person struggling against themself in the purest sense. A struggle to lose weight. Overcoming depression or a phobia. These are the most obvious generic examples, but let’s look at some specific ones.

Maybe the food quest is a gripping psychological piece about fighting your own laziness or depression, driven by mounting hunger pangs and the horrifying realization that there is nothing in the house that’s quick and easy to make.

Maybe the house is dark and quiet and leaving the comforting glow of your TV or desktop computer makes you nervous… the unease growing as each half-imagined creak, groan, or rustle goads your imagination that little bit closer to panicking. (This works best if you can find an excuse to keep the lights from working without also making the TV or computer portable. Is the house being renovated?)

An example of a novel-length person vs. self conflict would be a redemption story where the character’s greatest enemy is how they cling to old familiar behaviours and beliefs.

Person(s) vs. Society

What makes person(s) vs. society distinctive is the special middle-ground it occupies, where the antagonist is made by and of people, but they have ceded their agency and authority to it until it almost becomes a force of nature. “Everyone knows they’re wrong. Why would I even question that?”

A gang of people isn’t a society, and a villain with a lot of henchmen isn’t a society. Person vs. Society happens when the people blur together, too fleeting or too minor to be “the bad guy”, and that blur becomes the antagonist… like the story of someone with mental illness pitted against the neglect of a society that doesn’t understand them.

Some of the most famous dystopian stories are person(s) vs. society stories for this reason. How are you supposed to fight or reform something as big as a society and do so when nobody wants to give up the comfort of conformity to join you?

This is also a good fit for a story where the lead is an antihero, driven by circumstance to become the villain for someone else’s story… either to fail tragically in the end at the hands of their adversary, or to end their arc in some form of mutual redemption, reborn in the struggle to set right what drove them to villainy.

Think about how interesting it could be, but how uncommon it is, to read a tragedy, where you sympathize with someone who is forced to walk the path of the “bad guy” because circumstance has dictated that they must be sacrificed for the good of society, and to set themselves against unarguably good, heroic people and plans that will help many more people. Think of the opportunity for catharsis when they have their tragic fall.

Aside: Did you notice how easily terms like “bad guy” can bias your thoughts? Not just the obvious “What if the antihero is female?”, but also the more subtle tendency to see a “guy” as probably an ordinary, everyday person belonging to whatever demographic you do. …but what can we do? There’s a conceptual difference between a “bad guy” and a “bad person”, but not all “bad guys” are “villains” either. This is why it’s important to question everything for the good of your story.

Anyway, what would person(s) vs. society look like in our food example? That’s actually a very good question. I chose an example that is very small and mundane to show how anything can be a story… something that would be difficult to stretch out into a novella, let alone a novel, and society is inherently something that lends itself best to longer stories with greater significance. A novel, if not a series. It’s genuinely difficult to think about how society could believably interfere with something as quick, simple, ordinary, and routine as going to the kitchen for some food.

The first idea that comes to mind is that maybe it’s not so quick and simple. Maybe, whatever society is doing to make it a problem is chronic. We’re not seeing an isolated incident, but instead a representative sample of a big, ongoing problem.

That has potential, but we still need to find a conflict against society that can be solved in such a contained situation. Does it still count as enough of the same concept to satisfy this demonstration if we balloon the scope up and write a “but when she got there, the cupboard was bare” story? Where the protagonist leaves their game paused, struggles to put food on the table, and then comes back to resume their play. Until now, all of these were simple ideas more suited to a long short story or short novella. It seems unsatisfying to make an exception, when all the other examples could probably be rewritten to fit this larger scope, but I suppose it could work if they are gaming, then go to work, then come home and game some more.

Person(s) vs. Nature

It might be more accurate to call this “person(s) vs. the/their environment”. Person(s) vs. Nature is all about a character struggling against a passive, uncaring environment that has no agency, and opposes them purely by existing.

Examples of this include Cast Away (2000) where Tom Hanks struggles to survive alone on a tropical island, and Homeward Bound: The Incredible Journey (1993) where three animals who believe they’ve been abandoned cross the Sierra Nevada mountains to get home.

For our food example, maybe the house is cluttered… or being renovated… or you just broke your leg and you’re not used to walking on crutches… and you are upstairs while the kitchen is downstairs… and you don’t want to eat in the kitchen so you have to navigate all of the obstacles while carrying food.

Person(s) vs. Nature is traditionally thought of in the context of wilderness or the open ocean and, in the traditional literary criticism that may be true for all I know. However, as a tool for story planning, it’s about the environment passively opposing you just by existing. (You may encounter a bear, or a shark, but that animal isn’t “the antagonist”… just one piece of the “nature” that’s opposing you.)

Depending on how the story is told, a family struggling to maintain domestic normalcy in a war-torn country could count as this.

Person(s) vs. Fate

I said I’d explain why Person(s) vs. Fate is fundamental, so I’ll start with that.

What is Fate? It’s a force that doesn’t fit into any of the other categories:

  • It’s external to the character’s mind, unlike Self.
  • It’s active, unlike Nature.
  • It’s not embodied in one or more definite characters, like Person(s).
  • It’s not the collective actions and beliefs of a cultural group, like Society.

My favourite abstract example is when fate forces two people into conflict, but both are equally good or bad. Neither is “the bad guy”, and they’re not struggling against society, but something forced them into a situation where two protagonists are pitted against each other.

My favourite concrete example is a father and son who become separated. The father spends a decade losing hope that he will ever find his son, while the son spends a decade stewing in resentment over the misconception that he was abandoned… and then fate brings them together.

Both are sympathetic protagonists, but now that they’ve been brought together, the old status quo is no longer tenable. They can’t just forget about each other now that they’ve been reconnected. The son is right in feeling the hatred he does, but the father is also right in wanting to make peace. The only “villain” is fate, for separating them, keeping them separate, and guiding the son to become so emotionally invested in a perfectly reasonable misunderstanding. The story can only end in either some kind of grand sacrifice or a willingness to attempt reconciliation… and I don’t think the sacrifice would be very satisfying.

You could say that it’s almost a person(s) vs. self because they are trying to overcome their expectations and preconceptions, but not quite, because of how it isn’t just one person struggling against their own demons and it isn’t two protagonists allied against the problem. The bad guy was fate, placing their desires at odds, and then forcing them to deal with that unresolved past.

Academics agree that “man against nature” is one of the fundamental types of conflicts but omit “mang against fate”, but it’s much easier to say “Fate set up the conflict against Nature, so all ‘man against nature’ is a subset of Person(s) vs. Fate” than it is to dismiss Person(s) vs. Fate as akin to other proposed conflicts like “man against machine” or “man against God”. (Is the story casting the machine/God as a person, a force of nature, etc.? This is about how the author approaches writing them, not their cultural significance.)

That said, it’s pretty easy to intuit the difference between Person(s) vs. Nature and Person(s) vs. Fate when you compare examples of them. Just because fate crashed Tom Hanks’s plane in Cast Away (2000) doesn’t make his struggle to survive any less Person(s) vs. Nature.

(This is an important distinction. The conflict used to set up for the plot, like the plane crash in Lord of the Flies, isn’t necessarily the conflict that drives the story.)

Beavis and Butt-Head Do America (1996) would also count as a Person(s) vs. Fate. Their TV gets stolen and the conflict isn’t against the thieves. That motivates them to get up and go on an unexpectedly long journey through a collection of serendipitous events and unconnected people before finally finding their TV… it’s like Homer’s Illiad and Odyssey without Poseidon. 😛

So, how might a Person(s) vs. Fate story about getting a snack look? Well, maybe they want to just get some food and get back to their game, but new demands on their attention keep showing up now that they’ve left the solitude of their room. Murphy is out to get them, and Murphy doesn’t count as a person.

Important phone calls, family members who need help, etc. None of them are antagonists and they’re not conspiring in any way… fate just doesn’t like the main character and sets others up so their perfectly reasonable desires happen to interfere with the main character’s quest for food.

That said, I will admit this example doesn’t feel as clear and well-defined as the others. If anyone can suggest something better, please do.

When And Where Does It Start?

On an intuitive level, readers assign a lot of importance to a story having self-contained causality. That is, it shouldn’t feel like the author is reaching in and meddling after events have started. (In the theology of the narrative process, readers are deist, not theist.)

(This has important implications for all kinds of fiction, such as how you should aim for it to feel like all events are caused by characters. As an example, David Weber is particularly good at this and it allows him to pull off stuff which would seem contrived if you hadn’t seen how it came about from ordinary people acting in realistic ways. For an example of making even the most serendipitous things feel character-caused instead of author-caused, I suggest reading his book, Oath of Swords. Pay attention to how the ambush scene is set up.)

This becomes most visibly important in Alternate History stories and fanfiction. If you’re starting from a chronology your readers already know, then they will allow you one free “poke from the finger of God” at the beginning of the story, and everything else should appear to ripple out from that.

It doesn’t have to happen during your story (eg. It could happen thousands of years ago in a prologue), but it’s important for the readers to feel that everything has a solid, internally consistent causality, even if they can’t quite tell how event A caused event B.

This means that you can’t just say “chaos theory” and do whatever you want. Readers aren’t looking for actual causal connections, but a feeling that they exist… and, because they never truly forget that you’re pulling the strings, they’ll hold you to a higher standard of consistency than reality. (This is where that “truth is stranger than fiction” line comes from. We recognize that fiction is written by a human mind with the goal of telling a story, and we judge it based on that.)

Just like knowing your driving conflict and your chosen resolution, knowing your divergence event in an Alternate History story or fanfic will help you to stay on track.

As you might suspect, this is also one reason it’s so difficult to write a multi-cross (a fanfic combining elements from more than two source works). Your one “touched by the hand of Author” event gets the first two series to meet… but it’s much harder to find a reason for more to join in when they never crossed paths in canon. (The other reason it’s difficult is that, the more characters you mix in, the more difficult it is to give each one enough attention and the more it feels like you’re not doing the source material justice by cherry-picking what you do have time for.)

This is also why you can’t just arbitrarily borrow jargon, like using “Virtual Intelligence” outside a Mass Effect fanfic or calling your reactionless engines “impulse drive” outside of Star Trek. It’s too implausible for those terms to be chosen independently in two different series, so the reader applies Occam’s Razor and lands on the immersion-breaking answer that you, the author, were being lazy. (In the case of VI and AI, it’s implausible because no other franchise uses it and, in real life, we already have completely unrelated terminology that we use instead… “weak AI”, “narrow AI”, “control program”, or “expert system” versus “strong AI”, “general AI”, “AGI” (Artificial General Intelligence), or even “ASI” (Artificial Superintelligence) for AIs that are to us as we are to animals.

Let’s look at an example. Suppose you’re writing an alternate history story where U.S. foreign policy didn’t change course after FDR’s death. Even if you don’t show how everything connects, it’s important to understand the connections well enough that, if your editor or beta reader asks, you can explain your reasoning to them.

You don’t have to be certain (who can be in alternate history?), but you do have to be plausible. You don’t have to be shackled to reality, but you do have to write something that feels like it was set in motion and then left to run without the intervention of deus ex machina, overt or otherwise. You can still use things that might be judged dei ex machina, like the ending of Lord of the Flies, but you want them to feel merely unlikely… not an author reaching in and meddling with the story’s universe after it has started to run. Knowing your divergence event helps here.

Aside: The Two Kinds of “Starting”

Think back to that mention of a prologue and a divergence a thousand years in the past for a moment. This brings up the question of which kind of start we’re asking about.

Do we mean “When does the first important event happen?” or “Where does the story’s first scene take place?” …and how do prologues, time-skips, and flashbacks fit into it?

The more you think about it, the more you realize how important distinguishing the different kinds of “starting” is to that poorly phrased “start right into the action”. You don’t want to spend pages and pages setting up for “the good stuff”, but there’s a lot that probably happens to make “the good stuff” come to pass.

How much can you skip and then reference later as it becomes important? Would a prologue allow you to show the event that touches it all off, skip the build-up, and then start into the results? The better you understand “what your story is about”, the better you understand what to show, what to skip, and how to pace your story.

As for flashbacks, “When in doubt, don’t use them”. Good writing hooks the reader, but a hooked reader generally wants to see what happens next. For a flashback to work, you have to prepare the reader to care, not about what happens next, but what will be revealed next. For example, hooking the reader on the mystery of why a character is so different from what the reader expected them to be.

If you fail to achieve this, they’ll be chomping at the bit for the flashback to end so they can get to what they want to see. Good writing always primes the reader to care just as much about both choices when you cut away from one thing to another to let anticipation build, and jumping back in time makes that much more difficult because of our intuitive sense for causality and urgency.

In the end, it’s your story, but asking yourself these questions and making sure you have good answers will go a long way toward making your writing better. …and making it easier to bring in a friend or family member for a second opinion. This “User’s Manual” may be long but, once you’ve got the idea, this is just half a dozen questions you could fit on a sticky note. Make sure you can answer them to your own satisfaction, and writing will be easier and produce better results.

Posted in Writing | Leave a comment

Fanfiction – Taylor Inverse

Posted on 2022-08-07 by Stephan Sokolow

Taylor Inverse by Racke

Crossover: Worm/Slayers
Length: 4,497
Status: Oneshot

…and another Worm one. This time, a funny little Slayers crossover crackfic.

Since it’s just a oneshot, there’s not much to say about it. The gist is that Taylor is the reincarnation of Lina Inverse and, after the incident at Winslow, she assumes she needs to go on the run and winds up wandering around Brockton Bay, frustrating heroes and villains alike by not acting like a cape should.

What do I mean by that? She acts like Lina Inverse, but with a baseball bat and a wariness of inviting Mazoku in if she tries anything less drastic than a spell sourced from L-sama. Hero? Villain? Pshaw. She’s just wandering around, beating up any villains she encounters effectively enough that they assume she’s some kind of combat Thinker, and then blowing the money at the nearest good restaurant.

Here’s Coil’s opinion on it:

Coil very emphatically didn’t like Taylor Hebert.

The girl was a blind-spot in his plans, seeming to be somehow partially immune to his powers, which didn’t make any sense unless he started to try figuring out exactly how his powers worked.

He could split a time-line between two options, for however long he wanted, and then pick the time-line that benefited him the most. In other words, as long as there was an opportunity to win, he could be expected to grasp it. As long as he only needed to pick between two options.

However, any time that he gave an order directly related to Taylor Hebert, one of his time-lines would destabilize. Sometimes it would be the one where he told his mercenaries to stand down, other times it would be the one where he told them to attack.

There didn’t seem to be any rhyme or reason to which one collapsed, and it was driving him spare.

The fact that the girl had somehow recruited the Thinker that Coil had plans for, and was now squandering the potential asset by meandering around the city with a baseball-bat? That was just salt in the wound.

I won’t spoil the punchline at the end when she’s invited to an endbringer fight, but I will say it’s funny.

5 out of 5. Everything you want in a oneshot that’s of the “crackfic that takes itself seriously” variety.

…Just don’t post reviews on the fic. I recognize the author from another fic I read, they made it very clear in their author’s notes that they don’t want constructive criticism, and I don’t see the point in posting commentary at all if it’s just vapid “This was great! Moar!” stuff that a bot could post.

I’m honestly surprised they’re on Fanfiction.net rather than AO3, since their attitude seems more in line with AO3’s “don’t critique unless requested” culture and AO3 has an upvote-like “Give Kudos” button for “This was great! Moar!”.

Posted in Fanfiction | Leave a comment

The Out-of-Touch Autism-Spectrum Shut-in Social Survival Guide For People Who Are Paranoid About People, Parties, And Other P Words

Posted on 2022-08-01 by Stephan Sokolow

I don’t think I’ve mentioned it, but I tend to panic when I badly misjudge how something I said will be taken and then fail to recover. I recently learned that this is apparently called Rejection Sensitive Dysphoria. and I certainly have at least some of the “overcompensate and bend over backward in a desperate attempt to keep themselves in others’ good graces” part.

…so, while I work toward solving that, I thought some good might as well come of it, so here are my tips for when you really need to stay in people’s good graces with minimal stress:

  1. Socialize in non-realtime, textual media where you have time to think through what you want to say, it’s more excusable to take a break if you’re feeling impulsive, and it may help to keep you emotionally distanced. (This also protects you from being attacked for interrupting or talking over someone, whether because you have problems with impulsive behaviour or because they’re not giving you a chance to speak.)
  2. It’s OK to not have an opinion on something. (There’s supposedly an excellent Marcus Aurelius quote about this, but I’m having trouble confirming the cited source.)
  3. Don’t imply an opinion of someone’s knowledge/competence before you know. (“What have you tried so far?”, not “Have you tried [thing they might have been asked a million times before]?”)
  4. Find the most “give them the benefit of the doubt” way to interpret everything they say. If you’re wrong, they’ll demonstrate it soon enough but, if you’re right, you help to keep the conversation from falling apart. (This is actually something I picked up from a textbook for a university course on constructive discourse and debate.)
  5. If your perspective differs from someone else’s, express it as a “I was under the impression that… What am I missing?” question. (I also recently saw the phrase “help me understand” suggested as being very useful for keeping the conversation from taking a dive. (The example given being to ask someone to explain the behaviour of some code in a case that you think is buggy, rather than starting by accusing it of being buggy.)
  6. Double-check your facts against sufficiently reputable sources before stating them. (i.e. No matter how certain you are, at least search Wikipedia. It’ll take 30 seconds and you’ll surprise yourself sooner or later. If it’s a quote, turn to Wikiquote. They care about proper citations. If it’s not there, check the Talk page to see if it’s a common misattribution.)
  7. Don’t get defensive if a group you belong to is stereotyped or attacked… especially if they’re accusations of tribalism, over-sensitivity, immaturity, or something else that getting defensive will just be evidence of. (Look for some kind of “Yeah. They really suck.” response that sympathizes, de-escalates, and implicitly indicates that you don’t see yourself as part of the same sub-group as the people they’re basing their generalization on.)
  8. If you are guilty of a mistake that’s called out because you didn’t know any better, apologetically admit you’re trying to change. (People are more forgiving of people who are trying to change and as long as you are genuinely trying to change now, they don’t need to know whether you started trying a moment ago or a year ago.)
  9. Focus on what you agree on, not what you disagree on. (They’re unlikely to change their opinion based on the views of some random stranger, so it’s better to part on peaceful terms rather than stirring up needless strife. If you continue to interact, a non-hostile first impression will help to build their opinion of you as someone whose opinion may be worth considering.)
  10. If it’s a community you are going to be interacting with on an ongoing basis, rather than a one-time interaction, keep an eye out for in-jokes and slang to be learned, but don’t overestimate your ability to use them correctly. (i.e. Try to have a good sense of what their intent is so you can react appropriately, but err on the side of caution in which acceptable reaction you choose.)
  11. Don’t use language which can be taken as accusatory. (“I just can’t seem to find the right words”, not “You keep misunderstanding”.)
  12. Watch out for phrasing that comes across as “changing the subject to make it about you”. (i.e. Look for opportunities and phrasings that make it feel like you’re contributing to the existing direction of the topic.)

I don’t always remember to follow those rules, but I try. Heck, the last two were instrumental in leaving one probable troll over on Reddit very frustrated.

…now watch as some troll tries to use this as a roadmap for dismantling my armour and attacking me more successfully. People online suck. (See also Penny Arcade’s March 19, 2004 strip if you’re OK with a bit of profanity)

P.S. If anyone wants to try tracking down the source themselves, the supposed Marcus Aurelius quote is “You are not compelled to form any opinion about this matter before you, nor to disturb your peace of mind at all. Things in themselves have no power to extort a verdict from you.” but I’m having trouble confirming it to be from Meditations, Book 6 because Project Gutenberg’s copy uses a very different translation.

UPDATE 2022-10-18: I also like NYKevin’s strategy laid out here.

Posted in Web Wandering & Opinion | Leave a comment

Fanfiction – A Wand for Skitter

Posted on 2022-08-01 by Stephan Sokolow

A Wand for Skitter by ShayneT

Crossover: Worm/Harry Potter
Length: 359,078
Status: Complete

Continuing on the Worm crossover kick I seem to be on, how about an “adult Taylor Hebert reborn in the body of an 11-year-old muggleborn” story that is unusually good at focusing on the power dynamics of school children and portraying non-antagonistic dynamics between Snape and the focus character?

I think the best way to convey how this story works is to look at how she interacts with various different groups and, since I don’t feel like waiting until I’m didn’t wake up tired to re-draft this review, I’ll throw in more quotes than usual to cover up how choppy and repetitive the wordsmithing feels to me.

In Hermione’s case, Taylor’s background is used to to justify her recognizing Hermione as similar to who she used to be… even if she initially sees interacting with her to steer her in a more socially aware direction as a bit of a necessary chore. Taylor’s presence also has the side-effect of Hermione not being in the bathroom and, thus, not winding up with Harry and Ron.

I also like that the author understands Hermione well enough to recognize the implications of her choice of consequences for breaking the DA contract in fifth year:

“It’s not quite as important that we keep it secret as it was before,” I said. “That’s not to say I want anybody blabbing. But if he does start bragging to people, we’ll find ways to deal with it.”

“He won’t like how you deal with it, will he?” she asked. Hermione sounded almost gleeful.

She had a mean streak buried deep down; possibly it was the reason that we got along as well as we did. For all that she liked to pretend to be a good girl, she had a ruthless nature that I sometimes felt a little guilty for exploiting.

A Wand for Skitter, Chapter 54

Harry actually isn’t introduced to Taylor quickly though. This is one of those satisfyingly rare stories where the author sees the canon timeline as something to be shaped to their vision, rather than something to re-enact. Yes, she is in the same year, but the story doesn’t give any hint of that until she’s just about to actually go to Hogwarts and he’s kept completely off-screen until the winter holidays a third of the way through, aside from when a black-haired gryffindor boy with glasses is visibly paying attention to this unusual muggleborn Slytherin who steps in to head off trouble after Madam Hooch leaves during their first flying class.

As for Draco, she manages to maintain civil relations with him and exist as a walking indicator that he should think more carefully about his preconceptions.

“You know, Professor Snape has given orders for the prefects to give a speech about you this year.”

“What?”

“Most of them have likely heard about you, but there are always some that think they can make comments because they come from a good family.”

He sounded so superior to all of that.

“And what are they going to say?”

“The truth,” he said. “That your boggart is that you are going to murder us all and that bothering you will do the rest of us a favor.”

“What?”

“Professor Snape says that it’s good to cull the dunderheads early, lest they breed stupidity into the next generation.”

“Isn’t it a little late for that?” I asked.

Draco shrugged. “I wouldn’t know. Does that mean I’m stupid?”

I stared at him.

Making fun of himself? That showed a level of self confidence that I wouldn’t have expected from him.

A Wand for Skitter, Chapter 101

Among other reasons, because a post-canon Taylor who was shot from behind just after defeating Scion, who has been both hero and villain, and who woke up in the Harry Potter world as a survivor of an attempt to kill muggleborns on the Hogwarts roster does not take attempts by Slytherin students to bully her out of Slytherin lying down.

“If he was smart he’d have gotten a Pansy… I mean patsy to check his mail.”

Pansy gave me the finger from all the way across the table. She’d moved as far away from me as she could manage. She used the American gesture; apparently she’d gone to the trouble to learn that just for me. Apparently she’d been straining to listen in on our conversation as well.

A Wand for Skitter, Chapter 55

That said, it does escalate. This is a story where murder attempts eventually happen and named antagonists eventually die. However, it’s actually not one where I’d say that feels detrimental to the story… and I don’t mind, since it’s not going full “kill a very plot-significant character to prove that ‘no one is safe'”. No matter what story I’m reading, my emotional armour is on a hair trigger, so that’s pretty much a guaranteed emotional disengagement even in professional fiction.)

However, it is a 350,078-word completed story that covers the entire arc of winning against Voldemort, and it does do a pretty good job of getting the tone and scale for such an epic endeavour right, so that helps both Taylor’s approach to problems and the eventual character death fit in.

“So what do you intend to do about it?” I asked. “They just tried to murder possibly a quarter of the students remaining in Hogwarts. Whatever you think of muggles, do you think they’ll leave their children in this school once they found out what happened?”

“Nobody was hurt,” he said.

“Wizards think like that,” I asked. “Because they can heal from almost anything. Muggles are a lot more fragile, which means they ware even more protective of their children. If you don’t believe me, just ask professor…”

He waved his hands.

“I’ll think of something. The important thing is that you don’t spread rumors that I had anything to do with this.”

A Wand for Skitter, Chapter 69

Snape’s role in this is as a reluctant reformer at Dumbledore’s behest, including teaching her how to make dangerous potions safely after she re-creates Neville’s accidental boil-creating potion and almost kills Avery with an overdose of it when retaliating against an envelope full of Bubotuber pus.

“Giving people the benefit of the doubt will be the death of you,” Snape said.

“Not everyone can be redeemed.”

“And if I’d felt that way about you?”

Snape was silent for a moment. “It’s not normal for a child to be thinking about how to make me bleed to death.”

“I’d suspect that some of your students might disagree.”

There was a sound of expelled air, almost like Snape was trying to suppress a chuckle.

A Wand for Skitter, Chapter 7

As hinted at by that quote, Snape’s character and interactions with Taylor are, in and of themselves, worth reading for. For example:

“So you don’t think you need to check in on me?”

“I know I do,” he said. “But not because you are afraid. Compared to the hole I found you in, this must seem like a castle.”

“It is a castle.”

“Precisely.”

I stared at him, giving him a flat, unamused look. One should not encourage bad jokes; I’d learned my lesson with Clockblocker.

A Wand for Skitter, Chapter 8

All in all, it’s hard to make solid statements about characters’ roles because it uses that good kind of character writing where, if a character isn’t growing and changing, then the focus character’s perception of them is. (For example, it’s hard to sum up Snape succinctly, because, aside from being a complex character, Taylor keeps getting into situations that cause her perception of his opinion of her to shift.)

It also has some satisfyingly novel world-building and changes to the plot.

For example, Taylor gets detention in the Forbidden Forest, not because something is killing unicorns (because, in this timeline, Voldemort returned the year before Harry and Taylor went to Hogwarts), but because they’ve been keeping an eye on a unicorn mare who may need help with a difficult birth and that blend of threat (the forbidden forest) and peace (the Unicorn herd) is seen as suitable for students who have been caught fighting.

…or the castle having to be cleared of an infestation of new boggarts after Taylor’s class got traumatized by what the boggart turned into for some of them. This is returned to on several occasions, partly for plot reasons such as this:

The mercenaries in the front were backing away, green light flashing.

“You can’t kill me,” one of the Taylors said. “You think a Dark Lord would send you to kill one little girl? He’s sent you to die!”

Why were the Boggarts here, all of them?

It was the fear. The fear of over a hundred men, so thick that even my insects could smell it. It had to attract them like bees to nectar.

A Wand for Skitter, Chapter 114

…and partly for humour reasons. Both because it’s an amusing concept to read about teachers hunting down reports of monstrous versions of her loose in the castle and for moments like this:

As I went to bed that night, I saw the bodies of everyone I’d ever known piled in the corner.

“Riddikulus,” I said, pointing my wand.

The boggart skittered away and I went to sleep. My dreams weren’t good.

A Wand for Skitter, Chapter 79

All that said, the concept and how it’s implemented have a certain unavoidable “Author self-insert goes to Hogwarts” flavour to them. No matter how much an author dresses it up by finding or extrapolating an existing character who would agree with their perspective, that’s somewhat unavoidable when you have a crossover character rising to the challenge of steering history in a Harry Dresden-esque fashion… and it’s not helped by being written in first-person perspective.

(It’s also reminiscent of “adult Harry Potter” stories where Harry is an Auror or an unspeakable or something else and gets thrown into a situation. “Teen character, but aged up to adulthood” is a common technique fanfiction authors use to try to build an author surrogate or achieve OC-like results without accepting the reputation original characters have for poor quality writing.)

Good stories always suffer more from doing that than mediocre ones because there are so many stories that feel like that, unusually well written or not, and it becomes more noticeable as the story gets better.

I’m not sure whether it helps that her “jaded old soldier in a child’s body” personality makes many others see her as legitimately a potential threat if she snaps or whether that’s also close enough to certain “edgy” tropes that show up in various stories for its overall effect to balance out to zero.

It’s also interesting in that it starts to dip into Harry Potter Book 7 territory at around the half-way point, but then climbs back out of it fairly quickly… and, like in many other moments, it turns to clever original world-building to be familiar to canon events, but different. (eg. Their raid on the Ministry to destroy the source of the Trace… though I’ll caution that is a bit of a dropped plot thread, not really coming to anything.)

A moment later we were inside. Two more doors, and we reached what I thought had to be the source of the Trace.

I’d come across a historical record of the Ministry stealing an Analytical Engine; it had been created by Charles Babbage in the late 1830s as one of the world’s first computers. The official, muggle record was that it had never been completed by funding issues, but the truth was that he had been confunded and obliviated, and the engine had been stolen.

The Hogwarts Express had been acquired in a similar way, stolen from the very muggles that the Wizards determined to be inferior.

The engine was really nothing more than a primitive calculator, but my guess was that they wouldn’t have kept it here for that. They wouldn’t have enchanted it if they didn’t need it, and the timing… it had been stolen shortly before the Trace had been implemented was suspicious.

A Wand for Skitter, Chapter 77

(It’s nice to see Taylor recognizing that fraud or not, Gilderoy Lockhart knows PR, and going to ask his advice. Funny enough, in this timeline, thanks to spending time with Taylor, Hermione recognizes that Lockhart is a fraud early on.)

I do think it felt a bit surprising in an “author straining suspension of disbelief” way to have the Triwizard Tournament still crop up as an event, but at least playing with the timeline meant that Viktor Krum was too young to be part of the Durmstrang group, so that changes things up a bit, and the most novel part is probably that there isn’t a fourth champion.

I won’t spoil it, but there’s also an elegantly crafted point at the end of one chapter when I honestly started to worry that some accidentally discovered dark magic was going to make her walk the same path that turned Anakin Skywalker into Darth Vader… so desperate to gain the power to change things that they can’t see the road they’re walking.

Taylor IS sometimes overpowered, but, as mentioned, it reminds me more of Harry Dresden as I know him from the first Dresden Files book and a bunch of fanfiction. Yes, overpowered, but the narrative is engaging enough and satisfying enough to justify it as a means to an end.

The tone is darker than a lot of Harry Potter fanfiction, but it is a Worm crossover.

That said, there are occasionally moments of humour. For example, when Taylor decides to use exploding snap cards as the detonator for a barrel of gunpowder to take out a squad of Death Eaters.

The bugs had to slap the cards down with a certain amount of violence, which meant that I’d had to use nightmarishly large bugs. There had been some in the bowels of the castle that I hadn’t even been able to identify, including some spiders the size of a grown man’s fist.

In an effort to confuse the people watching, I’d set up a little green felt on the top of the barrel, and I’d dressed the spiders up in cute little gamblers outfits. I’d hoped that the incongruity of the scene would slow whoever saw it down for long enough.

A Wand for Skitter, Chapter 87

The way Voldemort goes down is very fitting and the epilogue is also surprisingly novel and satisfying. (Maybe it’s because it has that classic sci-fi flavour that I really need to get more of.)

…oh, and it does have (very) infrequent typos. I noticed a “Sevarus” and a “styill” (still), among others.

In the end, I’ll give it a 4.4 out of 5. It’s a satisfying and enjoyable story.

Posted in Fanfiction | Leave a comment

Tooltips for syntax highlights in QTextEdit/QPlainTextEdit

Posted on 2022-08-01 by Stephan Sokolow

While I was experimenting with adding nlprule-based grammar-checking to my spell-checked QPlainTextEdit subclass (not yet polished enough to share, but there’s a cut-down proof of concept for the nlprule integration on StackOverflow if you want it), I ran into a little problem.

Apparently, there’s an unresolved bug (QTBUG-80524 and duplicates) where QTextEdit and QPlainTextEdit don’t take syntax highlighter-set changes into account when figuring out whether to display a tooltip and what to show.

The solution? Override the lookup behaviour. Here’s how you do it:

class TooltipPlainTextEdit(QPlainTextEdit):
    def __init__(self, *args):
        QPlainTextEdit.__init__(self, *args)

        # Opt in to the events we need to override
        self.setMouseTracking(True)

    def event(self, event) -> bool:
        """Reimplement tooltip lookup to get nlprule messages working"""
        if event.type() == QEvent.ToolTip:
            # Get a secondary text cursor, taking margins into account
            pos = event.pos()
            pos.setX(pos.x() - self.viewportMargins().left())
            pos.setY(pos.y() - self.viewportMargins().top())
            cursor = self.cursorForPosition(pos)

            # QTextCursor doesn't have a quicker way to get
            # highlighter-applied formats, so find the one that our
            # cursor is inside
            for fmt in cursor.block().layout().formats():
                if (fmt.start <= cursor.position() and
                        fmt.start + fmt.length >= cursor.position()):

                    # Calculate the bounding box for the text and feed
                    # it as the rectangle for requesting that the
                    # tooltip auto-hide when the cursor exits
                    cursor.setPosition(fmt.start)
                    cursor.setPosition(fmt.start + fmt.length,
                                       QTextCursor.KeepAnchor)
                    QToolTip.showText(event.globalPos(), fmt.format.toolTip(),
                        self, self.cursorRect(cursor))
                    return True

        # Fall back to the default behaviour
        return super(TooltipPlainTextEdit, self).event(event)

…and that’s it. Your QTextCharFormat.setToolTip calls should now Just Work™.

Posted in Geek Stuff | Leave a comment

Fanfiction – When Life Gives You Lemons

Posted on 2022-07-24 by Stephan Sokolow

When Life Gives You Lemons by Baked The Author

Crossover: Worm/Portal
Length: 77,208
Status: Complete

What if Taylor Hebert triggered as a Tinker and then cobbled together a teleportation device that brought her to Aperture Science? What if GlaDOS and the other cores were more sane?

What do you get?

This is mostly a story about Taylor working her way through abandoned Old Aperture (Act 1), continuing to do so while interacting with the Aperture Science cast via radio (Act 2), and then staying alive in the face of a cleanly incorporated crisis and antagonist (Act 3).

However, it also constructs an alternate universe that is at once familiar, yet coherent, with details like Caroline being just as much a monster as Cave Johnson and GlaDOS actually originating as a digital upload of one of their department heads, a woman named Gladys Emerson.

It’s also got a nice sense of humour that’s very fitting for a Portal story, with segments like this:

but there were a few other useful pieces of trash lying around, along with a box of 15 Aperture Science Blueberry Granola Bars (“Tastes like real blueberries! Will never go bad, or else!”)

…as well as various other fun things that I’ll leave you to discover, because the setup is a little too long to be comfortably quoted.

A very satisfying “read it for the characters” story with some nice world-building… just don’t go into this expecting Taylor to meet them face-to-face or contact to be re-established with Earth Bet until the last couple of chapters.

At least 4.7 out of 5.

P.S. Look forward to seeing how, in this case, the cake is not a lie.

Posted in Fanfiction | Leave a comment

A QLineEdit Replacement with Spell-Checking

Posted on 2022-07-22 by Stephan Sokolow

TL;DR: Here’s the code

Today, I recevied a question which prompted me to revisit my old An Improved QPlainTextEdit for PyQt5 post and, along the way, I got a little nerd-sniped on the idea of adding spell-checking to QLineEdit too. (After all, I will need that for my own use sooner or later.)

Long story short, since QLineEdit doesn’t support syntax highlighting, you either have to re-implement the paint event yourself (which is a little too low-level for me to want to be responsible for shaking the bugs out of it) or you can just reconfigure QPlainTextEdit to look and act like QLineEdit.

It’s not perfect, since it can’t be used in situations like setting a custom QLineEdit subclass for a QComboBox… but since I already have a QPlainTextEdit that does spell-checking…

The process basically breaks down into two roughly equal parts: Working around the warts in how the QWidget APIs expect you to customize your widget sizing heuristics and everything else.

Start by turning off all word-wrapping and forcing the scrollbars to be hidden:

self.setLineWrapMode(QPlainTextEdit.NoWrap)
self.setWordWrapMode(QTextOption.NoWrap)
self.setHorizontalScrollBarPolicy(Qt.ScrollBarAlwaysOff)
self.setVerticalScrollBarPolicy(Qt.ScrollBarAlwaysOff)

Then, actually force the contents to stay on a single line. You’d think we could just use self.document().setMaximumBlockCount(1), but that disables Undo/Redo, makes Ctrl+V paste the last line when I think it’s more natural to preserve the first, and requires you to override keyPressEvent to prevent Enter/Key_Enter from erasing the contents of the field, so we have to go in manually:

def cb_textChanged(self):
    if self.document().blockCount() > 1:
        self.document().setPlainText(self.document().firstBlock().text())

self.textChanged.connect(self.cb_textChanged)

Going this route also makes it really easy to implement things like converting one-per-line lists of tags/keywords into comma-separated lists. Just replace self.document().firstBlock().text() with document().toRawText() or document().toPlainText() (depending on whether you want a little bit of Unicode normalization as described in the Qt docs) and do something like .replace('\n', ', ') before feeding it to setPlainText. (Though I’d probably use a QRegularExpression since it makes it easier to normalize whitespace while doing the conversion.)

Finally, the last difference I noticed and accounted for was the behaviour of the Tab key. That can be fixed as follows:

self.setTabChangesFocus(True)

def focusInEvent(self, e: QFocusEvent):
    """Override focusInEvent to mimic QLineEdit behaviour"""
    super(OneLineSpellTextEdit, self).focusInEvent(e)

    # TODO: Are there any other things I'm supposed to be checking for?
    if e.reason() in (Qt.BacktabFocusReason, Qt.ShortcutFocusReason,
                      Qt.TabFocusReason):
        self.selectAll()

def focusOutEvent(self, e: QFocusEvent):
    """Override focusOutEvent to mimic QLineEdit behaviour"""
    super(OneLineSpellTextEdit, self).focusOutEvent(e)

    # TODO: Are there any other things I'm supposed to be checking for?
    if e.reason() in (Qt.BacktabFocusReason, Qt.MouseFocusReason,
                      Qt.ShortcutFocusReason, Qt.TabFocusReason):
        # De-select everything and move the cursor to the end
        cur = self.textCursor()
        cur.movePosition(QTextCursor.End)
        self.setTextCursor(cur)

Now for the big hassle… redefining the widget sizing behaviour. You’d think that self.setSizePolicy(QSizePolicy.Preferred, QSizePolicy.Minimum) would be enough, but QPlainTextEdit defines unhelpful sizeHint and minimumSizeHint values and I don’t know where it’s getting them from.

I’ve seen other people doing various hacks, but I saw problems in all of them:

  1. Some people set the fixedHeight on the widget to the lineSpacing() given by the QFontMetrics from its font() … but that doesn’t properly account for the other various bits in the system like padding and borders from the QTextDocument and QStyle which become relevant when a widget is so short.
  2. Some people create a hidden QLineEdit with the same font settings, trigger layout calculations for it, and then harvest the values… but that’s just unacceptably hacky for me.

…so, here’s what I cobbled together from various sources. I don’t know if it’s 100% correct, but it seems to work:

def minimumSizeHint(self):
    """Redefine minimum size hint to match QLineEdit"""
    block_fmt = self.document().firstBlock().blockFormat()
    width = super(OneLineSpellTextEdit, self).minimumSizeHint().width()
    height = int(
        QFontMetricsF(self.font()).lineSpacing() +  # noqa
        block_fmt.topMargin() + block_fmt.bottomMargin() +  # noqa
        self.document().documentMargin() +  # noqa
        2 * self.frameWidth()
    )

    style_opts = QStyleOptionFrame()
    style_opts.initFrom(self)
    style_opts.lineWidth = self.frameWidth()
    # TODO: Is it correct that I'm achieving the correct content height
    #       under test conditions by feeding self.frameWidth() to both
    #       QStyleOptionFrame.lineWidth and the sizeFromContents height
    #       calculation?

    return self.style().sizeFromContents(
        QStyle.CT_LineEdit,
        style_opts,
        QSize(width, height),
        self
    )

def sizeHint(self):
    """Reuse minimumSizeHint for sizeHint"""
    return self.minimumSizeHint()

So… how well does it work? Well, here’s the full code. Try running it yourself. The demonstration will present it side-by-side with a regular QLineEdit.

(Let me know about any divergences in their behaviour that I missed so I can either fix them or document them as intentionally retained.)

Posted in Geek Stuff | Leave a comment