Other posts related to lyx-outline

 | October 26, 2010 5:05 pm

Note: Still working on the book, but because I needed a couple hour break, I decided to tackle some LyX-Outline stuff.  This post is related to one item on the to-do list.

Because I need to get away from the book for a while, I decided I would take a break and work on LyX-Outline stuff.  This includes one of the long-standing to-do items: adding support for sections of arbitrary length. Before I get too far down an implementation, though, I would like to request feedback from potential users.

I’ve been trying to find a good way to do this for several months and I think that I’ve finally determined how I would like for it to work.  (At least in the first release.)  Here’s what I propose:

  • Rather than hard-code a special inset into the C++, I think that I am going to add a style for these sections.
  • It will work as a module that you can add to any document you happen to be working on.  Special LyX-Outline templates will include the module by default.
  • The style will rank below all other headings in the document: section, subsection, subsubsection, paragraph, subparagraph.  This would allow for you to organize chunks of text in the body.  (I agree, it would be better to allow you to specify which level you would like this container to exist on, but LyX requires you to specify the indentation level of a particular heading.)
  • For higher level structures (e.g., section, subsection, subsubsection, paragraph, subparagraph), I would anticipate that you would use the other logical headings already provided by the document class.  For creative writing, I am creating layouts which include a heading for scene, that would work in a similar way to this “section of arbitrary length” but provide a container, so you can still group these arbitrary sections into folders.
  • Text in the title will not be added when you export/compile your document.
  • Like other types of section headings, you can add notes to them (which then appear in the corkboard and outline pane).
  • You can convert the “section of arbitrary length” title to a standard LyX/LaTeX section heading.

Does this proposal meet your needs?  This model would give you up to eight levels of hierarchy if working with one of the standard classes and up to four if working on a creative project.  Is that good enough?

After some investigation, I’ve found that completely adopting Scrivener’s model of an infinite number of folders/files would be extremely, prohibitively difficult in LyX.  Yes, it could be done, but it would require some significant rewrites to the way that LyX works.  My goal is to release LyX-Outline as soon as possible (literally, the day after the book has been finished) and I don’t want to get back into the business of major plumbing.  But if it is needed, I will.

There is also a second question.  What should these “sections of arbitrary length” be called?

Scrivener refers to blocks of text as “Chunks.”  That term in LyX, however, refers to something else.  (A block of code when using Sweave.)  LyX also reserves several other heading labels for use, meaning that “part”, “section”, “subsection”, “subsubsection”, “paragraph” and “subparagraph” are also out.

Anyone have any ideas?  I’m terrible when it comes to naming things, and if I make something up, it come out with a label like “Oak-Tree Anthropomorphic Writing Sections of Arbitrary Length”. That would just be bad, and humiliating.

Other people have recommended “Scrivening” and “Text-Block” as potential contenders, which I both like.  But I thought I would open the floor to other nominations before trying to make a decision.

 | July 19, 2010 9:00 pm

In the past few days, I’ve received several emails asking when LyX-Outline will be available.  (I had originally hoped to release an alpha/beta preview by July 15, which has not happened.)

This is a fair question.  I know that (yet) another self-imposed deadline has come and gone.  I know that this destroys confidence in the project as a whole and casts doubt on my ability to deliver.  I’m aware that it causes a “credibility crisis” and that it makes LyX-Outline look like “vaporware”, as one potential user was so … kind … as to point out.  But even knowing all of that, I’m afraid that I can’t give a firm answer to the question of, “When will you finally publish a binary?”  The simple truth is that I’m not sure when I’ll be able to finish.

Back in June, I was sure that I would have everything wrapped up by mid-July, then I discovered a raft of things that needed to be fixed.  Many of these tasks still aren’t done, so I’m revising my target date, again.  Instead of late July, my current guess is  early August.

But it really isn’t possible for me to commit to a firm date.  I have other responsibilities that need to take higher priority.  As a result, the official answer to the question of “When can I download LyX-Outline?” is this:

LyX-Outline will be available when it’s ready.

First impressions are forever, unfortunately; and I want both the alpha and beta releases to have a degree of polish.

If you are excitedly waiting for the release, however, I understand that this may not be what you would like to hear.  Solid, reliable dates are much better than tenuous goals and vapor.  For that reason, I’ve decided to publish my task list for the alpha milestone.  This will let you see what features I’m currently planning, provide an idea about how development is progressing and allow for you to provide input.  I will update the list as features are completed.

As always, I would be very interested in user feedback.  If you have any ideas for things you would like to see, please let me know in the comments or go to the project homepage and file a blueprint.  I would like to make LyX-Outline useful to as many people as possible.  For that to happen, though, I need your input.

Note: If you are a developer and see an unfinished item that sparks your interest, let me know.  Code contributions from anyone are welcome.  For instructions on how to check out/compile the current trunk version, see this post.

Show me more… »

 | July 13, 2010 6:38 pm

In the past few months, I’ve written several articles about the ways LyX can be customized.  These included a brief introduction to layout files and how they relate to document classes in addition to a tour of character styles and how you can add them to the LyX local layout.  What I have not written about, though, is one of the most important ways of extending LyX, the module.

Ever since version 1.6 of LyX, the core LyX developers have worked very hard to make LyX a modular system.  Instead of hard coding values and options – as they had done previously – they’ve instead placed all of the needed information in configuration files that can be edited and modified by users.  This is a Very Good Thng.  It means that (given enough motivation), you can customize LyX to behave exactly was you wish.  You can change the default document classes, styles, fonts and anything else that your little heart desires.  It also means that any extensions you create will exist as first-class citizens.  They have access to all of the internal wizardry as the default document classes and features.

In order to make this transition work, it was necessary to have certain chunks of code that could be switched on when needed and switched off when not required, and that’s how “modules” were born.  In a lot of ways, you might think of modules as document plugins.  They let you do stuff that, while not required, can greatly improve your editing experience.  (Modules are switched on and off from the “Document Settings” pane.)

They let you do things like run Sweave code, add additional theorem environments, or apply a different style to your text.  But unlike a layout file, they are not tied to any particular document class or type; which makes them very powerful.  In fact, nearly all of them they can be used with any document type that LyX supports.

There are two main types of modules:

  1. Modules that contain all of the code needed to implement a particular feature (or modify an existing one) and do not reference external packages.
  2. Modules that load existing LaTeX styles/packages and translate their features into insets, commands and headings.

In both cases, modules serve as a container for the code.  You can use a module to package code that would normally live in a document layout file, or you can use code that might have been placed in the local layout.  The code may be a document header, a new LaTeX command, a character style, a custom inset, or any other type of user customization that LyX supports.

The biggest difference between using a module instead of a layout, of course, is that when the code is placed in a module, you can then add it to any document on your system.  This makes modules a tremendously flexible way to reuse customizations that you’ve created.  In fact, in nearly all cases, they are the best way to package your customizations for use on your own system or for sharing with others.

In this article, I’d like to introduce the module.  I will explain its position in the larger LyX/LaTeX “big picture”, its internal anatomy and provide a few examples of how it can be used to add new features.

Show me more… »

 | July 1, 2010 5:50 pm

In the past few days, I’ve been thinking a lot about ideas and the tools that we use to capture and prepare them.  And, while doing so, I came to a rather obvious realization: there’s a lot of ways to seize thought and force it into another shape.

I mean, think about it for a moment: you can travel with a moleskin in your back pocket, send yourself an email, speak into your phone, or aggregate material from the Internet.  You can scrape, speak, jot, doodle or draw.  It’s ridiculously easy to do, and there’s certainly no shortage of tools to help you; which leads to a quandary.

Even though there are dozens (perhaps even hundreds) of different tools for capturing and manipulating ideas, I often feel the need to pick just one.  I want to aggregate, sort and manipulate all of my data (whether it be bound in numbers, images or text) in the same way and this need has resulted in many wasted hours searching for the One Tool that will meet all of my needs.

There is a big problem with such a strategy, however: it is destined for failure.

Not all thought is the same.  Even amongst similar specimens, the beasties likely have a texture and flavor that is utterly distinctive. The thinking required for a book chapter, for example, is not the same as that needed for an email; nor is the subtlety required for poetry present within most blog posts.

In some cases, the idea is like steak, in others it’s potatoes or onions; and like food, the grit of the thought determines how you prepare and consume it.  You certainly wouldn’t grill a cake, nor would you cook ribs in the microwave.  Those tools simply aren’t suited to the job.  Similarly, some ideas require a particular medium and trying to force them into another is like convincing a teenager to cut his hair.  The only way forward involves duct tape and an experience no one wishes to discuss later.

Thus, when facing a recalcitrant idea — as when dealing with defiant teenagers — the only only realistic option is to capitulate and suffer the eccentricities.  In some cases, the idea may demand that you capture it on pen on paper, perhaps even dictating a particular type of pen.  Such divas (I’m looking at you, Sarcasm) require that you savor each word or brush stroke.  Or, it may obligate you to type it out, as fast as you can, threatening to leave if you can’t keep up.

They’re fickle little bastards, ideas.

But just because ideas are wholly unique does not mean that they don’t have commonalities.  Nor does it mean that all ruminations are unreasonable.  You just have to match the idea to the right tool.  It’s like knowing that salmon should be poached in the dishwasher (PDF).

Which leads me back to my quandary.  Trying to classify ideas and determine an appropriate tool is daunting.  Yet, I have come up against a case (enforced by deadlines) where I need some answers.

Specifically, I need to figure out whether or not to include note-taking features into LyX-Outline.  And because I am unable to divine a solution on my own, I thought I would post an open inquiry as to the best way forward.  What say you, oh humble readers of this blog (and future users of LyX-Outline)?

LyX-Outline: Should Notes Really Live With a Project Draft?

On paper, one of the most compelling features in Scrivener (the Mac OS X program that I am using as an inspiration for LyX-Outline) is the ability to aggregate content into a research binder.  Scrivener makes it easy to pull in photos, PDF documents and other material, which you can then refer to while writing.

Unfortunately, while this feature sounds good in theory, I’ve found that it to be of limited practical benefit.  (At least for the type of writing that I do.)  Anything I use must be attributed, cited and properly foot-noted; and these are tasks which Scrivener doesn’t handle so well.  (For that matter, neither OneNote or EverNote, the other two note-taking programs I like to use, do a particular good job at it, either.)

Zotero (my favorite reference manager), on the other hand excels at tracking citations, files, and source-related notes.  It’s the main reason for it’s existence.  Even better, this information can then be synced to other computers and automatically inserted into my writing.  The fact that it is a permanent part of my reference library and available for reuse is only icing on the cake.  (Reusing text may be plagiarism; but reusing quotations/references is smart.)  But while Zotero may be perfectly suited for this class of notes and subset of ideas, in other places it is woefully inadequate.

Consider, for example, the notes, summaries, thoughts and scrivenings directly related to the structure of your writing.  For this material, trying to sort and save with Zotero is actually harmful.  When you place a note in Zotero, there’s a permanence to it. It becomes locked to a particular references and is only retrieved sporadically, thereby losing ts spontaneity and adaptability.

In fact, it is the dynamic ideas — which require the freedom to evolve and mature — that are those best suited to a tool like Scrivener or LyX-Outline.  They should live in close proximity to the text they describe and have the freedom to be moved, nested, split, and combined.  When the tool is adaptable, it’s easier to be innovative and fluid.

Which leads to an important development question: LyX-Outline needs a way to deal with both sets of ideas.  In the latter case, I’ve already created the Corkboard and Outliner.  But how should I deal with raw source material?

Should I try and incorporate a content manager/notes-feature into LyX-Outline (as Scrivener does)?  Or should I continue to use external tools and hone LyX-Outline as a writing environment?

As future users of this program, what do you think would be most helpful?

 | June 25, 2010 4:56 pm

Regular, scheduled reports are a a good way to ensure progress on a complex project.  There is just something about the need to routinely show what you’ve done and explain delays that helps people overcome procrastination and actually do their work.

This is particularly true for projects where there might not be another readily available incentive (such as a course grade or future employment).  It’s a tactic I’ve successfully used with fickle students and I’m discovering that it’s equally effective with fickle developers (like me).  Thus, I’m writing the first monthly progress report on LyX-Outline.

In case you’re new to the entire idea of regular reports, here’s what you can expect: a summary of recent progress, announcements, miscellaneously useful information, and conjecture about things that still need to be done.  Read on for more …

Show me more… »

 | May 24, 2010 4:27 pm

A little more than a year ago, I wrote an essay about writing.  I talked about how creative pursuits (at least for me) aren’t linear processes.  I explained how they often involve wandering about, getting lost in ideas, and general confusion.  Then, I ranted about how popular writing tools don’t allow for creative freedom.  They force you to work in a particular way rather than adapt to your needs.

But though most shackle you to a single workflow, not all are like that.  I highlighted a program on Mac OS X known as Scrivener and how it was an exemplar of software that I wanted to use.  And then, in the same breath, I railed against its limitations and bitterly complained that, while excellent for simple or creative writing, it didn’t handle complexity.

By the end of the essay, I decided to turn my frustration toward something productive.  Having looked at many available writing programs and not finding something that met my needs, I proposed something new: Why not take the creative features of Scrivener and integrate them into a program that excels at managing complexity?

People seemed to like this idea.  When I asked the developers of one such program (LyX) about it, they expressed support.  I got emails from potential users saying that such a tool would be of great benefit to them.  I even received a few donations to help “pay for my time.”

So, about two weeks after proposing the idea, I got to work.

In the beginning, the project progressed quickly. I was excited and motivated, and had the time necessary to make headway.  Within two months, I released a prototype and worked out most of the major design issues.  I even ported much of the prototype code from Python to C++ in preparation for the final phase of the project.

Then, I got stalled.

First, I got busy.  I decided to take on a new project at work and write a book.  I got frustrated with the lack of a decent backup program on Linux and decided to write my own.  My grandmother got sick and a lot of my free time filled with family commitments.

Second, I ran into “complications”.  While much of the user facing work – an improved outline pane, a navigational sidebar, and a corkboard – had been finished, there was still a lot to do behind the scenes.  I needed to write code that could integrate the Outliner with LyX itself and I needed to find a way for editing the document from specialized views.  (And it turned out that these two tasks were hard!)

Finally, my interests wandered.  Because of items one and two, I found that working on LyX-Outline wasn’t very much fun.  I’ve never care for C++, and I had no idea of how to proceed.  There were other things I needed to work on and I knew that re-starting LyX-Outline would require an enormous investment of time and energy. 

The end result was that I allowed my project to languish for the better part of ten months.  Until now, that is.

In the past few weeks, I’ve been hard at work and LyX-Outline has made some major progress.

Show me more… »

 | August 23, 2009 12:30 am

Note (May 26, 2010): The instructions provided here for filing bugs are out of date.  Since the time this article was posted, development for both Time Drive and LyX-Outline has moved to Launchpad.  The bugtracker below, http://www.oak-tree.us/bugtracker, no longer exists.

Even though software developers try and create a perfect product, every program has its flaws.  These can be show stopping, or merely annoying; but they are unavoidable.  Even so, unavoidability doesn’t mean that they should be tolerated.  Which is where users bear some responsibility.  If you want a better program, you need to provide feedback to the developer.

Given how important feedback is, I find it hugely ironic that many of the software programs used to solicit such feedback (called bugtrackers), are horrifically difficult to use.  Perhaps the single best (worst?) example is the system used by the Mozilla foundation (famed creators of Firefox and Thunderbird): Bugzilla.  The interface is backward, it’s impossible to find anything, and getting to the same page twice requires a minor miracle.

Knowing this upfront, I tried to find a very easy to use program for collecting feedback on LyX-Outline and Time Drive.  And I thought I had succeeded when I came across Flyspray, an open source bug tracking system.  While still remaining powerful, Flyspray is fairly easy to use for both developers and users.  Unfortunately, though, it hasn’t been quite easy enough.

You see, even though it’s pretty simple to open a new bug report, getting to the right place isn’t the most intuitive process in the world.  A number of people have expressed confusion about where to go to complain about Time Drive.  As a result, I thought i would write a brief guide.

Step 1: Go to the Bug Tracker Website

To get started, you need to head to the Time Drive and LyX-Outline bug tracker website.  It can be found at:

http://www.oak-tree.us/bugtracker

Step 2: Go to the Appropriate Project Page

When you load the page for the first time, you will see a list of the currently open bugs for all active projects.  Depending how busy I’ve been, this list could be quite long, or quite short.  What you won’t find on this page, however, is an easy way to add new bugs.  To do that, you’ll need to navigate to the project specific page.

The main window lacks any way of providing feedback.  This is because you are in the wrong place.

Look at the very left hand side of the tool-bar.  Underneath the username box, you will see a drop down list that says “All Projects.”  This magical list is the main way that you navigate my Flyspray based bugtracking system.

Select the appropriate project from the list and click "Switch"For example, let’s say that Time Drive just corrupted your vacation photos and you want me to know this and how angry it made you.   To communicate these thoughts (bonus points if you can do so without swearing), you need to go to the Time Drive project page.   This is as easy as clicking on the down arrow and choosing “Time Drive” from the options.  After you change the option, it is likely the page will refresh, and the main navigation menu will change.  (Though on some browsers, most notably Opera, you will need to click the “Switch” button.)

Now, instead of the utterly boring, “Overview” and “Tasklist” options, you should be presented with a slightly more exciting menu.  This includes the options to take a look at the “Roadmap” and more importantly, “Open a new Task anonymously.”

Step 3: Complain Loudly, Thoroughly and Convincingly

Once you are on the correct project page, you will be able to take a look at the project overview, browse the roadmap, or file your bug report.

This is where you need to complain.  Tell me exactly what you think of me, my creations, and my professionalism.  Rant about how Time Drive corrupted your carefully maintained comic book collection, or how LyX-Outline destroyed your thesis.  This information is important, it helps me to improve the programs.  And getting it off your chest might help you too.  Nothing is more soothing than a good rant.  Especially when the person on the other end really wants your input.

Squeaky wheels tend to greased.  Thus, consider this positing as my official permission to squeak.  But to be most effective, you need to make your noise in a place where it will get noticed.  For Time Drive and LyX-Outline, this happens to be at their respective project pages.