hurd.texi potential contribution

[Joshua Branson]

Hey Samuel,

So I have been working on some updates to the Hurd manual.  Some changes
are probably ready (once I figure out how to commit them.  I can't get
magit to work on the Hurd at the moment).  However, there are some other
changes where I am trying to document various Hurd functions.  Here is
an example:

#+BEGIN_SRC texinfo
@node Opening Files
@subsection Opening Files

FIXME: Looking up files in directories.  The comments from the code in
@file{hurd/fs.defs}, was copied in verbatium.  The function definitions
may be incorrect, because I have never used these functions before.

@deftypefun error_t dir_lookup (@w{file_t @var{file}}, @w{string_t 
@var{file_name}}, @w{int @var{flags}}, @w{mode_t @var{mode}}, @w{retry_type 
@var{do_retry}}, @w{string_t @var{retry_name}}, mach_port_send_t @var{result})
Translate a file name, following all symlinks.  Upon return, if
@var{DO_RETRY} is @var{FS_RETRY_MAGICAL} then @var{RETRY_NAME}
specifies what to do, the list of possibilities is documented in
@code{<hurd/hurd_types.h>}; if FS_RETRY_REAUTH, then @var{RESULT}
should be reauthenticated before being used.  If @var{RETRY_NAME} is
the empty string and the retry type is FS_RETRY_NORMAL, then no
further @code{dir_lookup} calls are required; @var{RESULT} is the port
to use.  Otherwise the @code{dir_lookup} call should be repeated, sent
to @var{RESULT} (or the reauthenticated port) with @var{RETRY_NAME}
passed for @var{FILE_NAME}.  This call is required to be supported by
all files (even non-directories) if the filename is null, and should
function in that case as a re-open of the file.
@end deftypefun

@deftypefun error_t dir_readdir (@w{data_t @var{data}}, @w{int @var{entry}}, 
@w{int @var{nentries}}, @w{vm_size_t @var{bufsiz}}, @w{int @var{out}})
Read entries from the directory.  Each entry is identified by an index
number starting at 0 and running through the file.  This call fetches
@var{NENTRIES} (or any convenient number if @code{NENTRIES} is -1)
entries starting at @var{ENTRY}, returning a series of @code{struct
dirent} in @var{DATA}.  Note that due to the variable-size
@var{D_NAME} field, @code{D_RECLEN} has to be used to jump from one
@code{struct dirent} to the other.  The number of entries successfully
read is returned in @var{AMOUNT}.  If @var{ENTRY} is bigger than the
index of the last entry, then 0 is returned in @var{AMOUNT}.  If
@var{BUFSIZE} is nonzero, never return more than @var{BUFSIZE} bytes
of data regardless.
@end deftypefun
#+END_SRC

When I eventually submit this, it will probably take a fair amount of
reviewing, because I know I am probably submitting incorrect function
documentation.  Any advice for how I can double check that I have
correctly documented each function?

Thanks,

Joshua

P.S.  Any suggestion for how I can get magit to work on Debian/GNU Hurd
again would be a great help too.  I tried using Emacs' tramp (from my
linux box), to ssh into the hurd.texi, so that I could use Linux's
Emacs' tramp-mode.  That failed to work too.  :(

-- 

Joshua Branson
Sent from the Hurd