subdocuments question

pviton's picture

swp 6.0.13 on MSWin

SWP6 appears to have support for
subdocuments, but it's not clear
that it's working (or working correctly).

To see this, start with the Std Latex
Article. Start a new section, give it a
title and type a few words of section text.

Now put the cursor in the new section
title, and do right-click, then
properties of section. In the resulting
dialog, note that you can check
"Keep as an included subdocument"
Check this, and provide a name,
say "subsec.tex". Click OK.
(The results below still hold if
you just say "subsec", ie without
providing an extension. It's not
clear what's expected here).

Now save your document. As far as I
can tell, nothing about the subdocument
is saved in the sci file; nor is it
saved in the enclosing folder or
indeed elsewhere on your disk.
So it's not clear just what has
happened. If you preview,
you get the entire document, and
still, nothing about the subdoc
appears to be created.

But there's worse. One nice thing about
SWP6 is that you can collapse sections,
so that the ones you're not working
on don't take up screen real estate.
You do this by clicking on the little gray
+ or - boxes to the right of the section
title. Do this with the section
you just declared as a subdocument.

You get a VERY scary message:

A script from "file://" is requesting enhanced
abilities that are UNSAFE and could be used to
compromise your machine or data:
Run or install software on your machine

followed by buttons for "Allow" or
"Deny". Click "Deny". What seems to
happen is that the +/- button actually
does what you wanted, (ie changes the
visibility state of the section)
independent of what you click.

Still, the message is a serious problem;
and, typically, none of this is
explained in Creating Documents.
It would be useful to have an
explanation as to whether (and if so,
how) the subdocument feature
is actually working.

xerenus's picture

Restricting a subdocument to

Restricting a subdocument to be the content of a chapter or section is fine. In fact this is exactly how I use SW5. My main documents consist of (chapter and) section headings. The content of each section forms a subdocument.

However, it seems that subdocuments in SW6 are little more that a mechanism for hiding content during editing. A subdocument is of type xml with no corresponding tex document created in the tex subfolder of the working folder. I'm not sure that this is working properly yet, but the xml subdocuments do not persist when closing the program.

Two main reasons why tex subdocuments are desirable are as follows:

* Data security: Subdocuments make it easier to isolate an error or corruption in a project. Then the worst that can happen is that a single subdocument has to be corrected or rewritten. Latex is human readable by contrast with xml. One can always open a tex file with with a tex (or text) editor. Imagine working with a large document in SW6 and it crashes due to some unknown error and will not reload. Then all you have to work with are single monolithic xhtml and tex files.

* Project management. It is good practice to work with individual documents (corresponding to sections) which retain their separate identity and integrity apart from the master document.

These are standard tex facilities supported in SW5x, LyX and other open source tex editors. I only hope they will be supported in SW6.

Barry MacKichan's picture

tl;dr. It does work. The +/-

tl;dr. It does work.

The +/- normally hides the content of a section or chapter. The content is still in the main.xhtml file.

If you use the section/chapter properties to "Keep as an included subdocument", then the +/- button reads/writes the content of the section/chapter to the disk. If you look at the working directory for the document you should find a file with the contents of the section. It has an .xml extension. 

If you preview the pdf when the section is collapsed, the section contents will not appear in the PDF or in the tex file.

In this way, you can create a large document with each chapter, or each section if you want, in a file of its own and load only the chapter you are working on. This will reduce the amount of work the program does, the amount of TeX that gets processed, and the size of the pdf you will proofread.

The message is scary. It does not come from our code, but I will revisit the question of whether we can pre-answer the question with a default preference of some sort. You should allow what it is asking. If you scroll down in the dialog, there is a check box that lets you avoid the dialog in the future, so you need to see it only once. I will change the default size for that dialog so the check box is always visible -- not always easy given the large range of screen sizes and resolutions that are available nowadays.



pviton's picture

Oh, I see - the subdocument

Oh, I see - the subdocument info (xml file) only gets written out when you collapse the section. I hadn't done this, which is why I didn't find anything subdocument-related.

Thanks also for pointing out what happens when you preview with a collapsed section: this also works as it should.

xerenus's picture

It is good that this question

It is good that this question has been raised. I purchased a SW6 license soon after it was released, hoping that sub-documents would be supported in due course. It was only through this posting that I discovered the Section Properties box which is ineffectual at present, presumably to become functional in a future release.

The facility to create and manage large documents as a hierarchical collection of smaller documents is crucial to the way I use SW. Many of my documents are articles and books which range from ten to hundreds of pages. I have 16 years of work produced with SW4x and SW5x. I have tried importing some of these into SW6 but find that the sub-documents are all combined into one monolithic document.

So far I have only been able to play with SW6. My impression is that it is potentially a significant evolution of SW5x but not yet usable for large projects. Several years ago, I started using SW5x with MikTeX. This setup allows me to do things that can be done with TeX/LaTeX but not with TrueTeX, like creating diagrams with TikZ and using the rsfs package for improved calligraphic letters.

I hope support for sub-documents will implemented in the near future and will allow such documents created in SW5.5 to be imported with preservation of sub-document structure. Then I will be in a position to test SW6 properly and contribute more to this forum.

Barry MacKichan's picture

The rules for what a

The rules for what a subdocument can be have changed. Only the contents of a chapter or a section can be in a subdocument. This guarantees that when a chapter's contents are written to disk, that the empty chapter and its header will stay in the "master document". This ensures that the chapter and section numbers or all visible chapters and sections will be correct. I say "visible" since if a section is contained in a chapter that is on disk, neither the section or its number will be visible. The hidden sections will not appear in the pdf table of contents.

So, importation will not preserve the sub-document structure of 5.5. I think the importation includes all the subdocuments and produces a single file. You can then chop it into pieces. Remember that the table of contents in the sidebar consists of clickable links so you can jump to chapters and sections easily.




xerenus's picture