#476 New command "Open as master"


Opens a file with the usual file dialog and assigns master status after successful opening. No-op on cancel or failure.


  • Tim Hoffmann

    Tim Hoffmann - 2013-06-05

    Not needed. I think, the file is automatically loaded as master now (implicit, not shown explicitly as master document).

    The whole concept of an explicit master document is somewhat bulky and should be removed.

  • Kirill Müller

    Kirill Müller - 2013-06-30

    Why would you want to remove the concept of a master document? This is very clear and maps 1:1 to typical LaTeX usage -- calling pdflatex on one file, which is the master document.

    What would be the alternative? Are you considering automatic detection? This can fail, and will fail for several of my use cases! What is the difference between an "implicit" and an "explicit" master document?

  • Tim Hoffmann

    Tim Hoffmann - 2013-07-02

    By "explicit" I mean the current editor-wide master document, which the user has to set manually. Drawbacks:
    + There's user action required to set that document. In particular, you have to do it everytime you want to work with that project.
    + You need to have the master document open (at least while setting it). But most of the time, you won't actually edit it, because it only holds the structure of your project (essentially some imports and includes).
    + There can only be one master document (i.e. current project) at a time. If you have more projects open, you have to switch manually.

    By "implicit" I mean, the correct document to run pdflatex on should be inferred from the currently active file. So no matter which file I currently view, I will have a pdflatex run which generates output with this file.
    The fail-save method for this is to use % !TeX root = masterfile inside the file. Benefits:
    + User action only once, when the file is created for the first time.
    + Syntax already used in TeXworks.
    + No need to do anything when loading or switching files.
    + You always compile the correct document.
    On top, there might be automatic detection for simple cases.

    Does this way fail in any of your use-cases? If so, please let us know.

  • Kirill Müller

    Kirill Müller - 2013-07-03

    Use cases: Several master document that create the same document with different options. Most generally, when files for a TeX project are not a hierarchy but a DAG:

    • Draft mode
    • Screen-optimized layout without margins
    • Documents using \documentclass{standalone} et al.

    Please keep supporting explicit master documents!

    To your drawbacks:

    1. Not anymore, if this issue were resolved :-) There could also be two menu items -- "Open document as master" and "Set master document". The latter would assign master role but not open the document.
    2. Ctrl+W is easy enough. OTOH, I don't seem to be able to assign master role with keyboard only.
    3. Use separate TeXstudio instances for separate documents with --start-always.

    The advantages of "implicit" master docs vanish when there's no clear hierarchy of files.

    Last edit: Kirill Müller 2013-07-03
  • Tim Hoffmann

    Tim Hoffmann - 2013-07-03

    Thanks for the feedback, I wasn't aware of these usecases.

    @1. Basically yes. I'm just trying to keep the menus not too crowded by making additional entries for basically existing functionality.
    @2. There are just not enough keys to assign every functionality of TXS to a shorcut.
    @3. That's somewhat tedious you either have to start from a commandline or have a separate shortcut for this in the UI. Both is not too user-friendly and not something I'd ask from the average user. In particular it doesn't work when double-clicking a tex file on win.

    Well have to think more on the master document thing.

    It's not exactly your request, but there's recently been a discussion on setting the master document by script. Maybe this can already help you.

  • Kirill Müller

    Kirill Müller - 2013-07-08

    @1. A checkbox in the "open" dialog would also do, but I'm not sure if Qt supports custom controls in the "File open" dialog.
    @2. It's just that the menu items from the tree context menu aren't accessible from the main menu. This makes them sort of a "hidden feature". If they were, I would assign a shortcut through the "Config" interface of TeXstudio, and this issue would be solved for me, too.
    @3. A quick search for "texstudio second instance" immediately finds the solution. But of course you could also offer... a menu item :-)

    Is there a magic comment that indicates that a file is a master document (as opposed to indicating the name of the master document in slave files)? What happens if more than one !TeX root magic comment is found?

  • Tim Hoffmann

    Tim Hoffmann - 2013-07-08

    @1. This is not possible because Qt uses the native file dialogs of the OS.

    @2. There is Options -> Define current Document as Master Document, which can be assigned a shorcut.

    Moreover, you can create a script


    If you like, you can also embed this into your master file:

    % !TeX TXS-SCRIPT = openroot
    % //Trigger = ?load-this-file
    % documentManager.setMasterDocument(documentManager.currentDocument)

    @4. I think there is no need for an explicit this-is-a-master-document tag. The TeX root comment has two functions (1) It determines the document to compile (e.g. argument to pdflatex). This is the original functionality also in TeXworks. (2) It tells TXS to look for context information (labels, citations, etc.) in that file or its descendants.
    Both are not required by the master document itself. (1) If you don't set any option, this file will be compiled. (2) All required information is in the descendants, which are given by \includes and \input.
    In that context it might make sense to define % !TeX include so that TXS can still be obtained even if you have defined \yourprivateinclude{file}. But that's another topic.

    One TeX root per file is ok. We don't guarantee a special behavior for multiple TeX root. IMO there is no correct way of handling such a situation.

  • Kirill Müller

    Kirill Müller - 2013-07-10

    @2. With an active master document, this is called "Normal mode (current master document: ...)". I have to click it before "Define current document as master document" becomes available. I think the latter should be always available, except when the actual master document is open.

    @4. If you could just leave the "explicit master" features in place, that would be great. On top of that, any kind of automatic detection can be implemented, as long the explicit master is honored.

    Thank you for your effort.

  • Tim Hoffmann

    Tim Hoffmann - 2015-08-23

    Automatic detection is the default. Explicit Root will remain as an option to handle special corner cases. There will be no separate "Open as Master" menu entry, because it wlll rarely be needed. If you have such a usecase, I propose to assign a shortcut for setting the master document role.

  • Tim Hoffmann

    Tim Hoffmann - 2015-08-23
    • status: open --> closed
    • Group: -->

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:

No, thanks