Merging upstream version 0.1.29.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 48 insertions, 0 deletions

diff --git a/debputy.pod b/debputy.pod
index 6017bf5..933b6d0 100644
--- a/debputy.pod
+++ b/debputy.pod
@@ -274,6 +274,54 @@ Folding ranges (multi-line comments).
 Note these features are subject to the editor supporting them, correct language IDs being
 passed to B<debputy>, etc.
 
+Options for this subcommand
+
+=over 4
+
+=item B<--ignore-language-ids>
+
+When provided, B<debputy> will ignore any language ID that the editor provides for any file. Instead, B<debputy>
+will only rely on the file name for determining how to interpret the file content.
+
+Since B<debputy> supports multiple file formats, it is needs to know what kind of file it is working with. The
+editor is supposed to provide this via a "Language ID" attribute. This enables you as a user in the editor
+to override the file format and have proper editor support no matter the filename. Unfortunately, most Debian
+packaging files do not have a language ID assigned in the LSP specification, so editors either provide a
+custom language ID or no custom language ID at all (that is, an empty string).
+
+When the editor does not provide a language ID for file, B<debputy> will since 0.1.25 automatically attempt
+to derive the language from the filename. With this option (introduced in 0.1.29), B<debputy> will always
+derive the language from the filename even if the editor provided a language ID. This can be helpful if your
+editor is providing language IDs that B<debputy> does not recognize.
+
+As an example, in B<emacs> with B<eglot> the language ID is derived from the name of the buffer's major mode. If
+you tried to use B<debputy lsp server> with a major mode that B<debputy> does not recognize then without this
+option, B<debputy> would "silently" do nothing. With this option, it would have worked provided the filename
+matched B<debputy>'s expectation no matter the major mode.
+
+On the downside, B<debputy> will not provide correct advice unless the paths matches F<< .../debian/I<filename> >>.
+This can provide issues with some setups where the debian directory is implicit such as some "packaging-only" repos
+or some editor scratch pads.
+
+=item B<--tcp> or B<--ws>
+
+By default, the B<debputy> language server will use B<stdio> for communication with the editor. These options provide
+either the TCP integration mode (B<--tcp>) or the websocket integration mode (B<--ws>). In this mode, the B<--host>
+and B<--port> options can be used to choose the bind address.
+
+These options are mutually exclusive.
+
+The B<--ws> option requires B<python3-websockets> Debian package.
+
+=item B<--host> I<HOSTNAME>, B<--port> I<PORT>
+
+With B<--tcp> or B<--ws>, these option determines the bind address. The default is 127.0.0.1 for host and 2087 for
+the port.
+
+In integration modes that does not need a bind address (such as the B<stdio> mode), this option is ignored.
+
+=back
+
 =item lsp editor-config B<EDITOR>
 
 Provide an example configuration glue for using the B<debputy lsp server> with the given editor