• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Liutauras Vilda
  • Bear Bibeault
  • Junilu Lacar
  • Martin Vashko
Sheriffs:
  • Jeanne Boyarsky
  • Tim Cooke
  • Knute Snortum
Saloon Keepers:
  • Ron McLeod
  • Tim Moores
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
Bartenders:
  • Scott Selikoff
  • salvin francis
  • Piet Souris

A look behind the scenes (Thank you to Janeice DelVecchio)

 
author & internet detective
Posts: 39663
785
Eclipse IDE VI Editor Java
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Janeice is a moderator here and focuses on the Cattle Drive. She is also one of the two tech editors of the book. Like me, Janeice is a fan of automated testing. And she brought it to the book.

She asked Scott and I if we would use a "book tool" if she wrote one. Sure!

Janeice wrote a small Spring boot program with POI/HSSF. It parses the Word docs and checks the chapter against some standards. For example, we are required to use certain styles. Or we want to be consistent about "class path" vs "classpath". The idea was that we could automate detection/prevention of some of the errata in our OCA 8 book. We found the tool valuable very quickly. We've added lots of rules to it.Some were things that were wrong. Some were things Scott and I wanted to stay consistent about.

It was even helpful to have book tools for the things we used to catch manually. Knowing book-tool would catch these things let us focus on content and work faster. Just like unit tests give you safety on your code, book-tools gave us safety for our book. And all the rules are unit tested. It's a perfect app for TDD because we are starting with scenarios.

So a big thank you to Janeice for book-tools!
 
Bartender
Posts: 1845
14
Eclipse IDE Spring Java
  • Likes 2
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
You're very welcome. I am really so happy you both liked it so much!
You and Scott did most of the work implementing all the rules you needed. My thing is just an engine to run the rules.

It was way more helpful to you than it ever was to me. I wanted to use it to run rules against the code in the text, but with all the snips and one liners, it was hard to write rules meaningful for the code at that level.
That said, it was really nice to know there were certain things that I didn't have to look for while I was editing.
 
Jeanne Boyarsky
author & internet detective
Posts: 39663
785
Eclipse IDE VI Editor Java
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Janeice DelVecchio wrote:You and Scott did most of the work implementing all the rules you needed. My thing is just an engine to run the rules.


And yet, it wouldn't have existed without you! The idea of writing the engine (and actually doing it) was all you!
 
Greenhorn
Posts: 10
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

the Word docs


Would LaTeX be an option for writing a book like yours?
 
Marshal
Posts: 66575
251
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Good to see you again, Janeice
 
author
Posts: 4172
29
jQuery Eclipse IDE Java
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Sander Hollaar wrote:

the Word docs


Would LaTeX be an option for writing a book like yours?



Yes.....  in fact previous books I worked on used LaTeX and I found type setting to be a heck of a lot easier (closer to a WYSIWYG editor), but alas... no.  Word is used because it has built in support for track changes and revisions.  Imagine 2 authors and 3-4 editors are all working on the same chapter.. lot easier to manage/review/approve changes in Word.

That said, we do shift to PDF after a chapter has been reviewed, but then we have to spend a great deal of time ensuring text is properly laid out.  Jeanne knows this is the part I get most nervous about.  On the plus side, we’ve gotten better about consistency so we have fewer and fewer problems moving to PDF.
 
Scott Selikoff
author
Posts: 4172
29
jQuery Eclipse IDE Java
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Janeice DelVecchio wrote:You're very welcome. I am really so happy you both liked it so much!
You and Scott did most of the work implementing all the rules you needed. My thing is just an engine to run the rules.



Did I though?  I remember early on I would implement my rules in the form of “Hey Janeice can you make this change...”.  

Seriously though, the book tool has been invaluable for consistency and also avoiding problems before they happen.  As stated earlier we move from word to pdf and parts (especially code snippets) aren’t formed properly, it can take a lot of time to fix.  Thanks Janeice for being a life saver on these books!
 
Sander Hollaar
Greenhorn
Posts: 10
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Imagine 2 authors and 3-4 editors are all working on the same chapter.. lot easier to manage/review/approve changes in Word.


Not to invalidate the point you make towards Word, but this sounds like something Github/Gitlab could provide as well. But likely not as sophisticated as Word. Thanks for the insight.
 
Jeanne Boyarsky
author & internet detective
Posts: 39663
785
Eclipse IDE VI Editor Java
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Scott Selikoff wrote:

Janeice DelVecchio wrote:You're very welcome. I am really so happy you both liked it so much!
You and Scott did most of the work implementing all the rules you needed. My thing is just an engine to run the rules.



Did I though?  I remember early on I would implement my rules in the form of “Hey Janeice can you make this change...”.  


I think you wrote a couple. I also remember the one where you specified the requirements in JUnit and asked me to implement the regex. I liked that one!

re LaTex - the publisher actually does support that as an option now. The problem is that the book already exists in Word. When we worked on the OCP 11 books, they gave us backed out Word files. So switching to LaTex now would be a lot of work.
 
Scott Selikoff
author
Posts: 4172
29
jQuery Eclipse IDE Java
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Sander Hollaar wrote:Not to invalidate the point you make towards Word, but this sounds like something Github/Gitlab could provide as well. But likely not as sophisticated as Word. Thanks for the insight.



You could, but I think Word is better for reviewing text documents.  Unlike code, which tends to be rewritten in functions or lines, text documents can have a lot more subtle differences.  Also, it allows us to visualize the edits for all changes, not just the most recent one, along with who modified what (based on color).  So, as much as I'd prefer LaTeX, I think it is useful post-submission in editing the document.
 
Marshal
Posts: 3838
66
Netbeans IDE Oracle Firefox Browser
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Did you encounter some difficulties managing the documents in Word? I participate on maintaining a documentation in the form of some largish Word documents, and it's sometimes terribly frustrating, as we keep hitting some obscure Word bugs. But our documents were created many versions of Word ago, and that seems to be part of the issue.

Also, which language/library does the book tool use? Is it a VBA or .NET?  (Or, hopefully, something else? )

How did you put together revisions by multiple authors/editors? Were you merging together documents that were edited offline, or did you all simultaneously edit one version stored in cloud?

Scott Selikoff wrote:You could, but I think Word is better for reviewing text documents.  Unlike code, which tends to be rewritten in functions or lines, text documents can have a lot more subtle differences.  Also, it allows us to visualize the edits for all changes, not just the most recent one, along with who modified what (based on color).  So, as much as I'd prefer LaTeX, I think it is useful post-submission in editing the document.


When I wanted to be able to track changes to a LaTeX document using versioning software, I was putting each sentence on a new line. That's ok with LaTeX, which uses two newlines to end a paragraph, but quite an unnatural way to write which took some time getting used to. It was then possible to track changes using the versioning software on a sentence level as opposed to a paragraph level, which is too coarse. I didn't actually co-author the document with anyone, so I don't know how this would turn out.

There are some LaTeX packages for comparing two versions of a document, making highlights similar to Word revisions, so it might be possible to pull two versions from a version control and compare them (not sure about the author information though). But it's quite a lot of setting up and additional work for something that comes out of the box using Word.
 
Janeice DelVecchio
Bartender
Posts: 1845
14
Eclipse IDE Spring Java
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Martin Vashko wrote:

Also, which language/library does the book tool use? Is it a VBA or .NET?  (Or, hopefully, something else? )



Java with spring boot and poi. Could have been done in any language that has a library for word doc. If it were docx, I would have used straight xml traversal.
 
Janeice DelVecchio
Bartender
Posts: 1845
14
Eclipse IDE Spring Java
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Campbell Ritchie wrote:Good to see you again, Janeice



Always good to see you.
 
Jeanne Boyarsky
author & internet detective
Posts: 39663
785
Eclipse IDE VI Editor Java
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
We are writing a book about Java. Using another language on the book would be heresy
 
Martin Vashko
Marshal
Posts: 3838
66
Netbeans IDE Oracle Firefox Browser
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Janeice DelVecchio wrote:Java with spring boot and poi. Could have been done in any language that has a library for word doc. If it were docx, I would have used straight xml traversal.


Thanks, that makes sense. I guess I spent too many years cobbling up makeshift tools to manipulate Office files using VBA...

Jeanne Boyarsky wrote:We are writing a book about Java. Using another language on the book would be heresy


Good point!
 
Live a little! The night is young! And we have umbrellas in our drinks! This umbrella has a tiny ad:
Java file APIs (DOC, XLS, PDF, and many more)
https://products.aspose.com/total/java
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!