This project has moved. For the latest updates, please go here.

This lib needs a FAQ..

Apr 13, 2016 at 3:14 PM
Edited Apr 13, 2016 at 3:33 PM
Working with this library is actually pretty horrible at the outset, because nothing really makes sense compared to established conventions and most actions are backwards relative to normal thought.

1)

here is one nice example that any c# coder should understand:

StringBuilder sb = new StringBuilder();
sb.Append("Hello").AppendLine("World");

What does my builder now contain?
HelloWorld\r\n


In DocX:

Paragraph p = //get a paragraph from somewhere
p.Append("Hello").AppendLine("World")

What does my doc now look like?

Hello\r\nWorld


What harebrained idea is that, to put the newline at the start of whatever text is passed in to AppendLine. You really should have followed MS conventions with things like stringbuilder for this


2)


Moving swiftly on..

Suppose I'm typing a doc out in Word itself, and I type:

Little Bo Peep CTRL-B has lost her sheep CTRL-B CTRL-I and doesnt know where CTRL-I to find them

As you might expect:

Little Bo Peep has lost her sheep and doesnt know where to find them

In DocX, I don't even know what para.Append("Little Bo peep").Bold().Append("has lost her sheep").Italic().Append("and doesnt know") will result in, but for sure Little Bo Peep will be in bold, and I suspect that "has lost her sheep" will be italics, and the rest will be plain..

So it was actually deliberately coded that formatting commands apply to the last bit of text pumped in, rather than setting a toggle on so that all future bits have it applied? Again, it's backwards compared to logical convention

3)

Why is some formatting a method, and some formatting a property (.Alignment vs .Bold() )

4)

Why is it so that we do:

table = document.AddTable() //add a table to the document?
document.InsertParagraph().InsertTableAfterSelf(table) //actually add the table to the document, otherwise it won't show up in the document


Perhaps, if you were going to have AddTable be a method that creates a table (but if you don't insert it, it doesnt add it) you should avoid calling it "Add..." because it doesn't add anything?! Calling it "CreateTable" would be more logical, but then why would a document be a logical factory for a Table? Why not just let Table have a constructor.. ?

I can't find any way to create a table with an unknown number of rows/columns and then dynamically increment them. OK, so columns isn't too much of a deal, as that's pretty standard in the database world. A DataTable has a fixed number of columns, but variable rows. I'd have much preferred it if a DocX Table had worked more like a DataTable (which IS a logical factory for a Row, but a DataSet doesnt try to be the factory for a DataTable).

As it is, right now, it's far easier to build a table as a DataTable, and then iterate it, creating a DocX Table.. Which is kinda horrific

So much about this lib needs explaining.. Please, can the author help the rest of us out and explain how his logic works so we stand a chance .. ? And for future updates, I implore.. Try and find something else in the core framework that works in a similar way (paragraph vs stringbuilder, table vs datatable for examples), and mimic that behaviour - MS pour huge effort into making things work logically, piggy backing on it is pure benefit without having to do the extensive R&D
Developer
Apr 13, 2016 at 3:40 PM
Thank you for opinion. I'm sure the product has grown from very simple to a more advanced library. During that time lots of people already have their code bases. Doing anything to method naming or how they should be behaving according to you will break that and will get complains all over the place.

Having said that you have couple of options:
  • As a free, open source product you can just move on to better alternatives.
  • If you decide other alternatives don't suite your needs you can always take the source code and fix things up to suit your needs
  • You can adjust to what library offers, do your project and move on
And last one:
  • Get the source code. Open it up, modify things as described by you which makes sense and apply to our code base on Git. At the same time make sure that backward compatibility is there.
There's no "Author" anymore. Cathal is gone. Right now it's only community project and it seems to be running ok for most of the people. It's not perfect, it has it's faults, things don't work. If it doesn't work for some people they ask here for help or fix it in source and deliver to project for project sake.

There are plenty of examples in Source Code (like 20+), surely you can go thru it and find what you need. If not look at option number 1.